antd 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 44a5ae69094c720b34c8d440aa9072ab3d83e192fc790351c9d08ab8d4ef6f8f
-  data.tar.gz: '0329577dd7ac059a32b8f6bd47369e0452d3f13679f8c37e5da245359772b339'
+  metadata.gz: d8d53161e99f51956a6ba0b004669faf4a0d28e7e6998e8abe9fdbec35f83bd2
+  data.tar.gz: d9a2b3e9cb282eaf712ca3783c92cff130dd1958106a62c1c88637e686c223a1
 SHA512:
-  metadata.gz: d36cc92042a95ea03a429f5a706fe208d5b4c9c9ff030bcaf7fe72014e7e50feb15a0dd8b26426183de8581d9a90357bdc326dac959ca7ca590a3efaf5726914
-  data.tar.gz: ec4d4aadcc549fde1a6214030934aedefe9ca948dc4c72177bfa82d237c85819eb4edf0890e8940444d63113208760fa222850ce423a9d9a77e1e5fd15a06d0b
+  metadata.gz: b621b9cf29751e81e87dbb03f3377898732ae3eb56bd10e165d39d6c597f1fcf67ccb31ffdffc5aee5fe7210fa58658e2080d37f3d54fd4759c1a93f9e9f50ee
+  data.tar.gz: b1f17116698f10e199db336aaf4bd415c6e750f102299408457692aeb602f06d238c339ce4a58fcfa679261d7d74fef8122edcaa03496b0a1b0dcee4bb1b01a7

data/README.md

@@ -18,7 +18,7 @@ gem install antd
 
 ## Compatibility
 
-This gem talks to a running [antd](https://github.com/WithAutonomi/ant-sdk/tree/main/antd) daemon; it does not join the network itself. Ruby 3.1+. Tested against antd 0.12.x. The REST client has no runtime dependencies; the gRPC transport (`Antd::GrpcClient`) needs the `grpc` gem, which is deliberately not a runtime dependency of this gem — add `gem "grpc"` yourself to use it.
+This gem talks to a running [antd](https://github.com/WithAutonomi/ant-sdk/tree/main/antd) daemon; it does not join the network itself. Ruby 3.1+. Tested against antd 0.12.x; the pointer methods need antd 0.16.0 or later, the first release with pointers. The REST client has no runtime dependencies; the gRPC transport (`Antd::GrpcClient`) needs the `grpc` gem, which is deliberately not a runtime dependency of this gem — add `gem "grpc"` yourself to use it.
 
 ## Quick Start
 
@@ -53,18 +53,15 @@ Install the gRPC gem (listed as an optional development dependency):
 gem install grpc grpc-tools
 ```
 
-Generate the Ruby protobuf/gRPC stubs from the proto definitions:
+The Ruby protobuf/gRPC stubs in `lib/antd/v1/` are generated from the proto
+definitions and committed. After changing the protos, regenerate them and
+commit the result (CI fails when they drift):
 
 ```bash
-grpc_tools_ruby_protoc \
-  -I../../antd/proto \
-  --ruby_out=lib --grpc_out=lib \
-  antd/v1/common.proto antd/v1/health.proto antd/v1/data.proto \
-  antd/v1/chunks.proto antd/v1/files.proto
+gem install grpc-tools -v 1.84.0   # the version the script pins
+antd-ruby/scripts/generate-protos.sh
 ```
 
-The generated files are expected under `lib/antd/v1/`.
-
 ### Usage
 
 ```ruby
@@ -87,7 +84,24 @@ puts "Retrieved: #{data}"
 ```
 
 The `GrpcClient` raises the same `Antd::AntdError` hierarchy as the REST
-client, translating gRPC status codes to the appropriate error subclass.
+client, translating gRPC status codes to the appropriate error subclass
+(an `ABORTED` whose status details — `GRPC::BadStatus#details`, the text
+the daemon sent — start with `Partial upload:` becomes
+`Antd::PartialUploadError`, with the chunk counts, `retryable` and
+`retention_known` parsed from that text — see
+[Partial uploads](#partial-uploads); any other
+`ABORTED`, including one that only mentions `Partial upload:` later in its
+text, stays a generic `Antd::AntdError`).
+
+The pointer and close-group errors share gRPC status codes with older ones, so
+the daemon names them in an `x-antd-error-code` trailer
+(`GRPC::BadStatus#metadata`). The client reads it on every call and, when it
+agrees with the status code, raises the same typed error as REST:
+`FAILED_PRECONDITION` + `POINTER_FINAL` → `PointerFinalError`, + `POINTER_FORKED`
+→ `PointerForkedError`, `ABORTED` + `CONFLICT` → `ConflictError`, and
+`UNAVAILABLE` + `CLOSE_GROUP_SHORTFALL` → `CloseGroupShortfallError` (`retryable`
+when the details close with `(paid attempt retained...)`). Without the trailer,
+`FAILED_PRECONDITION` stays a `PaymentError` and `UNAVAILABLE` a `NetworkError`.
 
 > **Note:** Wallet operations (address, balance, approve) and payment_mode are available via REST only.
 
@@ -146,6 +160,62 @@ client = Antd::Client.new(base_url: "http://custom-host:9090", timeout: 30)
 | `file_get_public(address, dest_path)` | Download a public file by address |
 | `file_cost(path, is_public, payment_mode: :auto)` | Estimate upload cost — returns `UploadCostEstimate` with size, chunks, gas, payment mode |
 
+### 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 file's data map, or another pointer) can be changed by the owner, and
+the owner can hand it over to another pointer for good. 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. An address the daemon holds no key for
+is a `BadRequestError`.
+
+**Every write pays** (about the price of one chunk), and every attempt pays
+again. The SDK never retries a request, and you should not retry
+`pointer_create`, `pointer_update`, `pointer_transfer` or `pointer_finalize`
+automatically either. Reads are free to retry; one during an update or churn
+can fail with `CloseGroupShortfallError`.
+
+Both `Antd::Client` and `Antd::GrpcClient` have these methods:
+
+| Method | Description |
+|--------|-------------|
+| `pointer_keys` | Addresses of the pointers this daemon holds keys for, so can write — `Array<String>` |
+| `pointer_create(owner, target, kind: nil)` | Create a pointer, paid by the daemon wallet — returns `PointerWriteResult` (`address`, `state_id`, `counter`). `AlreadyExistsError`, before paying, if it exists. `kind` is `PointerKind::CHUNK` (the default) or `PointerKind::POINTER` |
+| `pointer_update(owner, target, kind: nil)` | Point a pointer at a new target, creating it if needed — `PointerWriteResult`. `PointerFinalError`, usually before paying, once it was handed over or frozen |
+| `pointer_transfer(owner, recipient)` | Hand a pointer over for good to the recipient's pointer, which must exist. Irreversible. Returns `PointerTransferResult` with the close group's `finality` (nil, with `finality_error`, if that check failed; the transfer stands) |
+| `pointer_get(address)` | Read a pointer — `PointerRecord` (`counter`, `target`, `kind`/`kind_tag`, `is_final` / `final?`, `transferred_to`, the owner's public key). `NotFoundError` if there is none |
+| `pointer_resolve(address)` | Follow a chain of pointers to the target at its end — `PointerTarget` (`kind`, `kind_tag`, `target`) |
+| `pointer_finality(address)` | Ask the whole close group where a pointer stands — `PointerFinality`. Check `final?` before relying on a transfer |
+| `pointer_controller(address)` | Follow transfers to the pointer whose owner now decides — `PointerController` (`pointer`, `transfers`, `frozen`) |
+| `pointer_prepare(owner, op, target: nil, kind: nil, recipient: nil, include_signed_quotes: false)` | External signer: the daemon signs a `PointerOp::CREATE`, `UPDATE` or `TRANSFER` and quotes it — `PointerPrepareResult` (wave-batch `payments` for `payForQuotes()`; `signed_quotes` when asked). Needs no daemon wallet. Other writes to the pointer raise `ConflictError` until it is finalized or expires (one hour) |
+| `pointer_finalize(upload_id, tx_hashes)` | External signer: store the prepared write once paid — `PointerFinalizeResult`. A write that falls short after payment raises `CloseGroupShortfallError` with `retryable`: repeat the same call to store it against the same payment |
+
+Counters are `Integer`s. The daemon sends them as decimal strings, because a
+final state (a transfer or a freeze) sits at `Antd::POINTER_FINAL_COUNTER`
+(2^64 − 1), past what a JSON number keeps exactly in many languages. A counter
+that is not a decimal u64 raises `InternalError`; it never reads as 0.
+
+`PointerFinality#status` is one of the `Antd::PointerFinalityStatus` strings:
+`OPEN` (with the corroborated `counter`, or nil), `SETTLING`, `UNCONFIRMED` and
+`FINAL` (with the one final `state`), or `FORKED` (with every final state in
+`states` and the `majority`). Only `FINAL` means a transfer is beyond dispute.
+A status a newer daemon adds is kept verbatim (`status_known?` is false), so
+give a `case` over it an `else` branch. Unset fields read as `nil` on both
+transports: REST sends `null`, gRPC an empty string or no message.
+
+The daemon accepts addresses with a `0x` prefix but always returns bare hex;
+normalise before comparing.
+
+```ruby
+owner = client.pointer_keys.first
+client.pointer_create(owner, client.data_put_public("v1").address)  # pays
+client.pointer_update(owner, client.data_put_public("v2").address)  # pays again
+puts client.data_get_public(client.pointer_resolve(owner).target)   # "v2"
+puts client.pointer_finality(owner).status                          # "open"
+```
+
 ## Error Handling
 
 All errors inherit from `Antd::AntdError` and can be caught by type:
@@ -172,6 +242,151 @@ end
 | `TooLargeError` | 413 | Payload too large |
 | `InternalError` | 500 | Server error |
 | `NetworkError` | 502 | Network unreachable |
+| `PartialUploadError` | 502 (`code: "PARTIAL_UPLOAD"`) | Finalize stored some chunks but not all — subclass of `NetworkError` |
+| `ServiceUnavailableError` | 503 | Wallet not configured |
+| `PointerFinalError` | 409 (`code: "POINTER_FINAL"`) / gRPC `FAILED_PRECONDITION` | The pointer is transferred or frozen; nothing can change it |
+| `PointerForkedError` | 409 (`code: "POINTER_FORKED"`) / gRPC `FAILED_PRECONDITION` | The owner signed two final states and no majority holds either — subclass of `ForkError` |
+| `ConflictError` | 409 (`code: "CONFLICT"`) / gRPC `ABORTED` | A pointer write while a prepared write to it awaits payment, or an update that lost to a newer state |
+| `CloseGroupShortfallError` | 503 (`code: "CLOSE_GROUP_SHORTFALL"`) / gRPC `UNAVAILABLE` | Too few of the close group answered or stored; `retryable` is true only for a pointer finalize that kept the paid state |
+
+The pointer errors are read from the error body's `code` (gRPC: the
+`x-antd-error-code` trailer), so a 409 with one of those codes is not an
+`AlreadyExistsError`. `CloseGroupShortfallError` is not only for pointers: a
+daemon with the pointer API reports a close group that fell short on any call
+(a chunk store, say) this way, where older daemons sent a 500
+(`InternalError`). It is not a `ServiceUnavailableError`, so rescue it by name.
+
+### Partial uploads
+
+A `finalize_upload` / `finalize_merkle_upload` / `finalize_chunk_upload` call
+can fail *after* the external signer has paid: some chunks store, others miss
+quorum after the daemon's own retries. The daemon reports this as HTTP `502`
+with `code: "PARTIAL_UPLOAD"` (gRPC `ABORTED`), and the SDK raises
+`Antd::PartialUploadError` carrying `chunks_stored`, `chunks_failed`,
+`total_chunks`, `retryable` and `retention_known`. The on-chain payment
+persists and the stored chunks stay on the network; what to do next depends
+on what the daemon said about the paid attempt:
+
+- **`retryable`** (antd >= 0.14.0; implies `retention_known`) — the daemon
+  kept the paid attempt under the same `upload_id`. Call the **same finalize
+  method again with 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 this error 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.
+- **`retention_known && !retryable`** — the daemon confirmed nothing was
+  retained (a merkle finalize with deliberately unpaid batches). Re-prepare
+  the same content: already-stored chunks are skipped, so the retry pays only
+  for the remainder.
+- **`!retention_known`** — retention is unknown: the error did not say, in a
+  form the SDK could read, whether the paid attempt was kept. The daemon may
+  still hold it (it records the resume handle before it returns the error).
+  Stop automatic recovery, keep the `upload_id` and the original payment
+  artefacts (tx hashes, or the merkle 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 REST, `retention_known` is true only when the body's `retryable` is a
+JSON boolean (`true` or `false`); absent, `null` or any other type reads as
+unknown. Over gRPC there is no structured body, so the counts and flags are
+parsed from the status text,
+`Partial upload: <stored>/<total> chunks stored, <failed> failed after retries: <reason> (<hint>)`.
+`retention_known` is true only when the text starts with that counts
+pattern, all three counts parse (each within the daemon's u64 range), and the
+text ends with one of the daemon's two hints: `(paid attempt retained...)`
+sets `retryable`, and `(stored chunks persist; re-prepare the same content...)`
+means the daemon confirmed nothing was retained (daemons older than 0.14.0
+write only this one). If the counts cannot be read, all three are `0` and
+both flags are `false`. Readable counts with a missing, truncated or
+unrecognised hint keep the counts, but both flags stay `false`: retention is
+unknown, so stop and reconcile rather than re-prepare.
+
+`PartialUploadError` subclasses `NetworkError` (the 502 mapping), so existing
+`rescue Antd::NetworkError` blocks keep catching it; rescue the subclass first
+to handle it specifically.
+
+```ruby
+MAX_ATTEMPTS = 5
+last_failed = nil
+attempt = 0
+begin
+  attempt += 1
+  result = client.finalize_upload(prep.upload_id, tx_hashes)
+rescue Antd::PartialUploadError => e
+  # Not resumable. With retention_known, nothing was retained: re-prepare.
+  # Without it, retention is unknown: stop, keep upload_id + tx_hashes and
+  # reconcile before re-preparing or paying again.
+  raise unless e.retryable
+  stuck = !last_failed.nil? && e.chunks_failed >= last_failed
+  raise if attempt >= MAX_ATTEMPTS || stuck    # bounded: same payment, same upload_id
+  last_failed = e.chunks_failed
+  sleep(2 * attempt)
+  retry
+end
+```
+
+See [`docs/external-signer-flow.md` section 6](../docs/external-signer-flow.md#6-retry-a-partial-store--same-upload_id-same-payment)
+for the daemon contract and `examples/07_external_signer.rb` for a
+`finalize_with_retry` helper.
+
+## Manifests
+
+A manifest (ADR-0006) describes a set of files in one `.ant` file or
+`ant://` link: each entry has an optional path and size, and either an
+embedded DataMap (from a private upload; the manifest is then the key to the
+file) or a public file's DataMap address. The daemon builds and decodes
+manifests, so the SDK never handles the format itself. These methods need
+antd 0.16.0 or later.
+
+**Nothing is uploaded or paid for.** Building one from DataMaps and addresses
+you already hold is free. Embedding roots (on build) and `resolve` (on
+decode) read from the network, so either can time out; retrying is safe.
+
+Both `Antd::Client` and `Antd::GrpcClient` have these methods:
+
+| Method | Description |
+|--------|-------------|
+| `build_manifest(entries, name: nil, torrent_info_hashes: nil, embed_roots: true)` | Build a manifest — returns `BuiltManifest` (`manifest`, the raw `.ant` bytes; `link`, or nil when it would exceed 1,500 bytes; `entries`, sorted by effective name). Each entry is a `ManifestEntryInput` or a Hash with `path`, `size`, and exactly one of `data_map` (hex) or `address` (hex); both or neither raises `BadRequestError` (400, the daemon's wording) before anything is sent. By default the daemon resolves each shrunk DataMap and embeds its root when it is at most 64 KiB; `embed_roots: false` embeds them as given |
+| `decode_manifest(manifest, resolve: false)` | Decode `.ant` bytes — returns `DecodedManifest` (`source`, `name`, `torrent_info_hash_v1`/`_v2`, `entries`) |
+| `decode_manifest_link(link, resolve: false)` | Decode an `ant://manifest/` link, a file link or a bare 64-hex address (a `ManifestSource::FILE_LINK`: one public entry, no path) |
+
+Each entry comes back as a `ManifestEntryInfo`: `effective_name` (the path,
+or the content address when there is none), `path`, `size` (what the
+manifest records: the creator's claim), `kind` (`ManifestEntryKind::EMBEDDED`
+or `PUBLIC`), `content_address`, `data_map` (decode only, embedded entries
+only, in the hex form `data_get` and `file_get` take), `exact_size`, and
+`error`. With `resolve: true` the daemon fetches each DataMap (not the
+content) to fill in `exact_size`; an entry that fails gets an `error` instead
+of failing the call.
+
+`manifest` is always raw bytes: the SDK base64-encodes it for REST and sends
+it as-is over gRPC. Sizes are `Integer`s, and anything a manifest leaves unset
+is `nil` on both transports, so a missing `size` or `exact_size` is `nil`,
+never `0`. An entry the daemon rejects (a bad path such as `../x`, a malformed
+DataMap or address) raises `BadRequestError` (gRPC `INVALID_ARGUMENT`) with
+the daemon's message, which names `entries[i]`. The SDK's own checks (both or
+neither of `data_map` and `address`, an empty manifest or link) raise the same
+error with the daemon's exact text, so the two cannot be told apart.
+
+Over gRPC, a manifest can be up to 64 MiB, past gRPC's 4 MiB default, so the
+client talks to ManifestService on a channel of its own with the send and
+receive limits raised to `Antd::MANIFEST_GRPC_MAX_MESSAGE` (256 MiB). The
+other services keep the defaults.
+
+```ruby
+a = client.data_put_public("one").address        # pays
+b = client.data_put_public("two").address        # pays
+built = client.build_manifest(
+  [{ path: "notes/one.txt", address: a }, { path: "notes/two.txt", address: b }],
+  name: "notes"
+)                                                # free
+File.binwrite("notes.ant", built.manifest)
+client.decode_manifest_link(built.link, resolve: true).entries.each do |e|
+  puts "#{e.effective_name}: #{e.exact_size} bytes"
+end
+```
 
 ## Examples
 
@@ -182,3 +397,6 @@ See the [examples/](examples/) directory:
 - `03_chunks.rb` — Chunk put/get
 - `04_files.rb` — File upload and download
 - `06_private_data.rb` — Private data put/get
+- `07_external_signer.rb` — External-signer prepare/pay/finalize with a bounded partial-upload retry
+- `08_pointers.rb` — Create a pointer, update it, resolve it and check its finality. Run with `ANTD_POINTER_OWNER=<address>` (one of `pointer_keys`); `ANTD_BASE_URL` overrides the daemon URL. Each write pays
+- `09_manifests.rb` — Store two pieces of public data, build a manifest of them, print its link and entries, and decode the link with `resolve`. `ANTD_BASE_URL` overrides the daemon URL. The two uploads pay; the manifest calls do not

data/lib/antd/client.rb

@@ -217,6 +217,16 @@ module Antd
     # @param tx_hashes [Hash<String, String>] map of quote_hash to tx_hash
     # @return [String] network address of the stored chunk
     #   (matches +PrepareChunkResult#address+)
+    # @raise [PartialUploadError] when some chunks stored and others did not
+    #   (HTTP 502, +code: "PARTIAL_UPLOAD"+). The payment persists. If
+    #   +retryable+, call this method again with the same arguments to store
+    #   the remainder against the same payment (antd >= 0.14.0). If
+    #   +retention_known+ but not +retryable+, nothing was retained:
+    #   re-prepare the same content, which skips stored chunks. If
+    #   +retention_known+ is false, retention is unknown: stop, keep the
+    #   upload_id and payment artefacts, and reconcile before re-preparing
+    #   or paying again. See +PartialUploadError+ and
+    #   docs/external-signer-flow.md section 6.
     def finalize_chunk_upload(upload_id, tx_hashes)
       j = do_json(:post, "/v1/chunks/finalize", {
         upload_id: upload_id,
@@ -365,6 +375,16 @@ module Antd
     # @param upload_id [String] the upload ID from prepare_upload
     # @param tx_hashes [Hash<String, String>] map of quote_hash to tx_hash
     # @return [FinalizeUploadResult]
+    # @raise [PartialUploadError] when some chunks stored and others did not
+    #   (HTTP 502, +code: "PARTIAL_UPLOAD"+). The payment persists. If
+    #   +retryable+, call this method again with the same arguments to store
+    #   the remainder against the same payment (antd >= 0.14.0). If
+    #   +retention_known+ but not +retryable+, nothing was retained:
+    #   re-prepare the same content, which skips stored chunks. If
+    #   +retention_known+ is false, retention is unknown: stop, keep the
+    #   upload_id and payment artefacts, and reconcile before re-preparing
+    #   or paying again. See +PartialUploadError+ and
+    #   docs/external-signer-flow.md section 6.
     def finalize_upload(upload_id, tx_hashes)
       j = do_json(:post, "/v1/upload/finalize", {
         upload_id: upload_id,
@@ -378,6 +398,16 @@ module Antd
     # @param winner_pool_hash [String] hash of the winning pool commitment
     # @param store_data_map [Boolean] whether to store the data map on-network
     # @return [FinalizeUploadResult]
+    # @raise [PartialUploadError] when some chunks stored and others did not
+    #   (HTTP 502, +code: "PARTIAL_UPLOAD"+). The payment persists. If
+    #   +retryable+, call this method again with the same arguments to store
+    #   the remainder against the same payment (antd >= 0.14.0). If
+    #   +retention_known+ but not +retryable+, nothing was retained:
+    #   re-prepare the same content, which skips stored chunks. If
+    #   +retention_known+ is false, retention is unknown: stop, keep the
+    #   upload_id and payment artefacts, and reconcile before re-preparing
+    #   or paying again. See +PartialUploadError+ and
+    #   docs/external-signer-flow.md section 6.
     def finalize_merkle_upload(upload_id, winner_pool_hash, store_data_map: false)
       j = do_json(:post, "/v1/upload/finalize", {
         upload_id: upload_id,
@@ -387,8 +417,250 @@ module Antd
       parse_finalize_response(j)
     end
 
+    # --- Pointers ---
+    #
+    # Owner-signed, paid, mutable references (antd 0.16.0 or
+    # later). The daemon signs with owner keys it loaded at
+    # startup (+antd --pointer-keys <file-or-dir>+), so a write names the
+    # pointer by its address (+owner+); +pointer_keys+ lists the pointers it
+    # can write.
+    #
+    # Every write pays, about the price of one chunk, and every attempt pays
+    # again. This client never retries a request, and callers must not retry
+    # +pointer_create+, +pointer_update+, +pointer_transfer+ or
+    # +pointer_finalize+ automatically (the one exception: a finalize that
+    # raised +CloseGroupShortfallError+ with +retryable+). Reads are free to
+    # retry.
+    #
+    # Addresses are 64 hex characters. The daemon accepts a 0x prefix but
+    # always returns bare hex, so normalise before comparing.
+
+    # The addresses of the pointers this daemon holds owner keys for. Only
+    # these can be written.
+    # @return [Array<String>]
+    def pointer_keys
+      j = do_json(:get, "/v1/pointers/keys")
+      (j["keys"] || []).map { |k| k["address"] || "" }
+    end
+
+    # Create the pointer at +owner+, pointing at +target+, paid by the daemon
+    # wallet. Pays; do not retry automatically.
+    # @param owner [String] address of the pointer to write
+    # @param target [String] address to point at
+    # @param kind [String, nil] +PointerKind::CHUNK+ (the daemon's default when
+    #   nil) or +PointerKind::POINTER+
+    # @return [PointerWriteResult]
+    # @raise [AlreadyExistsError] before paying, if the pointer exists
+    # @raise [BadRequestError] if the daemon holds no key for +owner+
+    def pointer_create(owner, target, kind: nil)
+      pointer_write("/v1/pointers", owner, target, kind)
+    end
+
+    # Point the pointer at +owner+ at +target+, paid by the daemon wallet,
+    # creating it if it does not exist. Pays; do not retry automatically.
+    # @param owner [String]
+    # @param target [String]
+    # @param kind [String, nil] see +pointer_create+
+    # @return [PointerWriteResult]
+    # @raise [PointerFinalError] if the pointer was handed over or frozen
+    #   (usually before paying; see +PointerFinalError+)
+    # @raise [ConflictError] if a prepared write to it awaits payment (refused
+    #   before paying), or the update lost to a newer state while in flight
+    #   (possibly after paying); read the pointer before writing again
+    def pointer_update(owner, target, kind: nil)
+      pointer_write("/v1/pointers/update", owner, target, kind)
+    end
+
+    # Hand the pointer at +owner+ over to the pointer at +recipient+, for
+    # good, paid by the daemon wallet. Readers of +owner+'s address are
+    # redirected to the recipient's pointer, which only its owner can move.
+    # Irreversible once stored. Pays; do not retry automatically.
+    #
+    # Refused before paying if +recipient+ does not exist or leads back
+    # (+BadRequestError+), and usually if the pointer is already final
+    # (+PointerFinalError+). A +CloseGroupShortfallError+ means too few of the
+    # close group answered or stored it. That can happen before paying (the
+    # transfer checks every peer first) or after, so check the pointer with
+    # +pointer_finality+ before paying again.
+    #
+    # @param owner [String]
+    # @param recipient [String] address of the recipient's pointer
+    # @return [PointerTransferResult]
+    def pointer_transfer(owner, recipient)
+      j = do_json(:post, "/v1/pointers/transfer", { owner: owner, recipient: recipient })
+      PointerTransferResult.new(
+        address: j["address"] || "",
+        state_id: j["state_id"] || "",
+        finality: j["finality"].is_a?(Hash) ? parse_pointer_finality(j["finality"]) : nil,
+        finality_error: presence(j["finality_error"])
+      )
+    end
+
+    # Read the pointer at +address+.
+    # @param address [String]
+    # @return [PointerRecord]
+    # @raise [NotFoundError] if no pointer exists there
+    def pointer_get(address)
+      j = do_json(:get, "/v1/pointers/#{address}")
+      PointerRecord.new(
+        address: j["address"] || "",
+        owner: j["owner"] || "",
+        counter: Antd.parse_pointer_counter("counter", j["counter"]),
+        kind: j["kind"] || "",
+        kind_tag: (j["kind_tag"] || 0).to_i,
+        target: j["target"] || "",
+        state_id: j["state_id"] || "",
+        is_final: j["is_final"] == true,
+        transferred_to: presence(j["transferred_to"])
+      )
+    end
+
+    # Follow a chain of pointers from +address+ to the target at its end.
+    # @param address [String]
+    # @return [PointerTarget]
+    # @raise [NotFoundError] if a pointer on the chain does not exist
+    def pointer_resolve(address)
+      j = do_json(:get, "/v1/pointers/#{address}/resolve")
+      PointerTarget.new(kind: j["kind"] || "", kind_tag: (j["kind_tag"] || 0).to_i, target: j["target"] || "")
+    end
+
+    # Ask the whole close group where the pointer at +address+ stands. Check
+    # it before relying on a transfer: only +PointerFinality#final?+ means the
+    # transfer is beyond dispute.
+    # @param address [String]
+    # @return [PointerFinality]
+    def pointer_finality(address)
+      parse_pointer_finality(do_json(:get, "/v1/pointers/#{address}/finality"))
+    end
+
+    # Follow the transfers from +address+ to the pointer whose owner now
+    # decides what it resolves to.
+    # @param address [String]
+    # @return [PointerController]
+    def pointer_controller(address)
+      j = do_json(:get, "/v1/pointers/#{address}/controller")
+      PointerController.new(
+        pointer: j["pointer"] || "",
+        transfers: (j["transfers"] || []).grep(String),
+        frozen: j["frozen"] == true
+      )
+    end
+
+    # External signer: sign a pointer write with the daemon's loaded owner key
+    # and quote it, without paying. The external signer pays +payments+ with
+    # +payForQuotes()+ and then calls +pointer_finalize+. The daemon needs no
+    # wallet. While the prepared write awaits payment (up to an hour), other
+    # writes to the same pointer raise +ConflictError+.
+    #
+    # @param owner [String] address of the pointer to write
+    # @param op [String] +PointerOp::CREATE+, +UPDATE+ or +TRANSFER+
+    # @param target [String, nil] create / update: the address to point at
+    # @param kind [String, nil] create / update: see +pointer_create+
+    # @param recipient [String, nil] transfer: the recipient's pointer
+    # @param include_signed_quotes [Boolean] also return each quote in full
+    #   signed form (+PointerPrepareResult#signed_quotes+)
+    # @return [PointerPrepareResult]
+    def pointer_prepare(owner, op, target: nil, kind: nil, recipient: nil, include_signed_quotes: false)
+      body = { owner: owner, op: op }
+      body[:target] = target unless target.nil?
+      body[:kind] = kind unless kind.nil?
+      body[:recipient] = recipient unless recipient.nil?
+      body[:include_signed_quotes] = true if include_signed_quotes
+      j = do_json(:post, "/v1/pointers/prepare", body)
+      PointerPrepareResult.new(
+        upload_id: j["upload_id"] || "",
+        op: j["op"] || "",
+        address: j["address"] || "",
+        state_id: j["state_id"] || "",
+        counter: Antd.parse_pointer_counter("counter", j["counter"]),
+        payment_type: j["payment_type"] || "",
+        payments: (j["payments"] || []).map do |p|
+          PaymentInfo.new(quote_hash: p["quote_hash"], rewards_address: p["rewards_address"], amount: p["amount"])
+        end,
+        total_amount: j["total_amount"] || "",
+        payment_vault_address: j["payment_vault_address"] || "",
+        payment_token_address: j["payment_token_address"] || "",
+        rpc_url: j["rpc_url"] || "",
+        signed_quotes: (j["signed_quotes"] || []).map do |q|
+          SignedQuoteEntry.new(
+            quote_hash: q["quote_hash"] || "",
+            quote: q["quote"] || "",
+            commitment_sidecar: presence(q["commitment_sidecar"])
+          )
+        end
+      )
+    end
+
+    # External signer: store a prepared pointer write once it is paid.
+    #
+    # A write that falls short after payment raises +CloseGroupShortfallError+
+    # with +retryable+ set: the daemon kept the paid state, so call this again
+    # with the same +upload_id+ (+tx_hashes+ is then ignored) to store it
+    # against the same payment. Bound that loop; the session expires with the
+    # daemon's one-hour pending TTL. Any other failure ends the session.
+    #
+    # @param upload_id [String] from +pointer_prepare+
+    # @param tx_hashes [Hash<String, String>] each +quote_hash+ from
+    #   +payments+ to the +payForQuotes()+ transaction hash
+    # @return [PointerFinalizeResult]
+    def pointer_finalize(upload_id, tx_hashes)
+      j = do_json(:post, "/v1/pointers/finalize", { upload_id: upload_id, tx_hashes: tx_hashes })
+      PointerFinalizeResult.new(
+        address: j["address"] || "",
+        state_id: j["state_id"] || "",
+        counter: Antd.parse_pointer_counter("counter", j["counter"]),
+        finality: j["finality"].is_a?(Hash) ? parse_pointer_finality(j["finality"]) : nil
+      )
+    end
+
     private
 
+    # POST a pointer create / update. +kind+ is omitted when nil, so the
+    # daemon applies its default (chunk).
+    def pointer_write(path, owner, target, kind)
+      body = { owner: owner, target: target }
+      body[:kind] = kind unless kind.nil?
+      j = do_json(:post, path, body)
+      PointerWriteResult.new(
+        address: j["address"] || "",
+        state_id: j["state_id"] || "",
+        counter: Antd.parse_pointer_counter("counter", j["counter"])
+      )
+    end
+
+    # Parse a pointer finality JSON object. The daemon sends +null+ for every
+    # unset optional (+counter+, +state+, +majority+, +transferred_to+); each
+    # reads as nil.
+    def parse_pointer_finality(j)
+      PointerFinality.new(
+        address: j["address"] || "",
+        group: (j["group"] || 0).to_i,
+        answered: (j["answered"] || 0).to_i,
+        status: j["status"] || "",
+        counter: j["counter"].nil? ? nil : Antd.parse_pointer_counter("finality counter", j["counter"]),
+        state: j["state"].is_a?(Hash) ? parse_pointer_final_state(j["state"]) : nil,
+        states: (j["states"] || []).grep(Hash).map { |s| parse_pointer_final_state(s) },
+        majority: j["majority"].is_a?(Hash) ? parse_pointer_final_state(j["majority"]) : nil,
+        transferred_to: presence(j["transferred_to"])
+      )
+    end
+
+    def parse_pointer_final_state(j)
+      PointerFinalState.new(
+        state_id: j["state_id"] || "",
+        kind: j["kind"] || "",
+        kind_tag: (j["kind_tag"] || 0).to_i,
+        target: j["target"] || "",
+        holders: (j["holders"] || 0).to_i,
+        transferred_to: presence(j["transferred_to"])
+      )
+    end
+
+    # A wire string, or nil when absent, +null+ or empty.
+    def presence(value)
+      value.is_a?(String) && !value.empty? ? value : nil
+    end
+
     # Parse a /v1/upload/finalize JSON response into a FinalizeUploadResult.
     #
     # +data_map_address+ is populated only when prepare was called with
@@ -483,6 +755,10 @@ module Antd
     end
 
     # Perform a JSON HTTP request and return the parsed response body.
+    #
+    # A non-2xx response is raised via +Antd.error_for_response+, which maps
+    # the body's +code+ / +error+ (and the PARTIAL_UPLOAD counts) onto the
+    # typed +AntdError+ hierarchy.
     def do_json(method, path, body = nil)
       uri = build_uri(path)
       http = Net::HTTP.new(uri.host, uri.port)
@@ -505,14 +781,7 @@ module Antd
       code = response.code.to_i
 
       unless (200...300).cover?(code)
-        msg = response.body.to_s
-        begin
-          parsed = JSON.parse(msg)
-          msg = parsed["error"] if parsed["error"]
-        rescue JSON::ParserError
-          # use raw body as message
-        end
-        raise Antd.error_for_status(code, msg)
+        raise Antd.error_for_response(code, response.body)
       end
 
       return {} if response.body.nil? || response.body.empty?
@@ -524,9 +793,9 @@ module Antd
     # they arrive. Reuses the same base-URL / timeout / error-mapping plumbing
     # as +do_json+, but never buffers the success body in memory.
     #
-    # On a non-2xx response the (short) body is read fully, parsed for an
-    # +{"error":...}+ field, and raised via +Antd.error_for_status+ — mirroring
-    # +do_json+. On 2xx, chunks are streamed straight to the block.
+    # On a non-2xx response the (short) body is read fully and raised via
+    # +Antd.error_for_response+ — mirroring +do_json+. On 2xx, chunks are
+    # streamed straight to the block.
     def do_stream(method, path, body = nil)
       uri = build_uri(path)
       http = Net::HTTP.new(uri.host, uri.port)
@@ -550,14 +819,7 @@ module Antd
           code = response.code.to_i
 
           unless (200...300).cover?(code)
-            msg = response.body.to_s
-            begin
-              parsed = JSON.parse(msg)
-              msg = parsed["error"] if parsed["error"]
-            rescue JSON::ParserError
-              # use raw body as message
-            end
-            raise Antd.error_for_status(code, msg)
+            raise Antd.error_for_response(code, response.body)
           end
 
           response.read_body do |chunk|
@@ -599,14 +861,7 @@ module Antd
           code = response.code.to_i
 
           unless (200...300).cover?(code)
-            msg = response.body.to_s
-            begin
-              parsed = JSON.parse(msg)
-              msg = parsed["error"] if parsed["error"]
-            rescue JSON::ParserError
-              # use raw body as message
-            end
-            raise Antd.error_for_status(code, msg)
+            raise Antd.error_for_response(code, response.body)
           end
 
           buffer = +""