antd 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ab6786553e76394691c28a2968384dd279738e876ecf961e74a0b7b46904cc0e
-  data.tar.gz: a04836fdba38a5457a3cfda27c3adde84bc8175a87dcd1c58e719fb315cc1f0a
+  metadata.gz: d8d53161e99f51956a6ba0b004669faf4a0d28e7e6998e8abe9fdbec35f83bd2
+  data.tar.gz: d9a2b3e9cb282eaf712ca3783c92cff130dd1958106a62c1c88637e686c223a1
 SHA512:
-  metadata.gz: '0806f4881413dd24b52a385319ee23ca30de479dea639b54ef0088bd31f8f0cdba73c0d458843082f697e6a92a3bb4c1f5c34dd77532d38d8032dcb4845f3c78'
-  data.tar.gz: 12fffe89716557c9dc2716a99f5f8b39a4958251387050f8828f45ff69628e2350e5aa6dc370f55a89d3abfc06fbb214770bf9cd1c31e516e794fc09daaf9fd4
+  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
@@ -96,6 +93,16 @@ the daemon sent — start with `Partial upload:` becomes
 `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.
 
 ## Prerequisites
@@ -153,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:
@@ -180,6 +243,18 @@ end
 | `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
 
@@ -256,6 +331,63 @@ See [`docs/external-signer-flow.md` section 6](../docs/external-signer-flow.md#6
 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
 
 See the [examples/](examples/) directory:
@@ -266,3 +398,5 @@ See the [examples/](examples/) directory:
 - `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

@@ -417,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

data/lib/antd/errors.rb

@@ -58,6 +58,66 @@ module Antd
     def initialize(message) = super(message, status_code: 503)
   end
 
+  # The pointer is at its final state, transferred or frozen: nothing can
+  # update it or hand it over again (HTTP 409 with +code: "POINTER_FINAL"+;
+  # gRPC FAILED_PRECONDITION with +x-antd-error-code: POINTER_FINAL+).
+  # Usually refused before anything is paid: the daemon reads the pointer
+  # first. A write that was already paid for when the network refused it (the
+  # pointer became final while the write was in flight) keeps that payment, so
+  # read the pointer before paying again.
+  class PointerFinalError < AntdError
+    def initialize(message) = super(message, status_code: 409)
+  end
+
+  # The pointer's owner signed two different final states and no one of them
+  # is held by a majority of the close group, so there is no answer to give
+  # (HTTP 409 with +code: "POINTER_FORKED"+; gRPC FAILED_PRECONDITION with
+  # +x-antd-error-code: POINTER_FORKED+). Subclasses +ForkError+, so
+  # +rescue Antd::ForkError+ catches it too.
+  class PointerForkedError < ForkError
+  end
+
+  # The request conflicts with the resource's current state (HTTP 409 with
+  # +code: "CONFLICT"+; gRPC ABORTED with +x-antd-error-code: CONFLICT+). For
+  # pointers, two cases share this code, and it does not say which one
+  # happened or whether anything was paid: a write while a prepared write to
+  # the same pointer awaits payment is refused before paying (finalize the
+  # prepared write, or wait for it to expire); an update that lost to a newer
+  # state while it was in flight may already have been paid for. Read the
+  # pointer again and check what was paid before submitting another paid
+  # write.
+  class ConflictError < AntdError
+    def initialize(message) = super(message, status_code: 409)
+  end
+
+  # Too few of an address's close group answered, or took a write, for the
+  # result to be the network's (HTTP 503 with +code: "CLOSE_GROUP_SHORTFALL"+;
+  # gRPC UNAVAILABLE with +x-antd-error-code: CLOSE_GROUP_SHORTFALL+).
+  #
+  # Reads are free to retry; one during an update in flight or churn usually
+  # clears. A paid write is not, unless +retryable+ is true: a pointer
+  # finalize then kept the paid state under the same +upload_id+, and
+  # repeating that finalize stores it against the same payment. Over REST
+  # +retryable+ is the body's +retryable+ (true only for JSON +true+); over
+  # gRPC it is read from the "(paid attempt retained...)" hint that closes
+  # the status details.
+  #
+  # Not a +ServiceUnavailableError+ (which means a daemon without a wallet):
+  # rescue it by name. Daemons without the pointer API reported a shortfall as
+  # a 500, an +InternalError+.
+  class CloseGroupShortfallError < AntdError
+    attr_reader :retryable
+
+    # @param message [String]
+    # @param retryable [Boolean] whether a pointer finalize kept the paid state
+    def initialize(message, retryable: false)
+      @retryable = retryable == true
+      super(message, status_code: 503)
+    end
+
+    alias retryable? retryable
+  end
+
   # A finalize stored some chunks while others remained unstored after the
   # daemon's retries (HTTP 502 with +code: "PARTIAL_UPLOAD"+; gRPC ABORTED).
   # The on-chain payment persists and the stored chunks stay on the network.
@@ -222,13 +282,77 @@ module Antd
     }
   end
 
+  # Metadata key the daemon (0.16.0 or later) sets on gRPC
+  # statuses whose code is shared with older errors, carrying the REST +code+.
+  ANTD_ERROR_CODE_METADATA = "x-antd-error-code"
+
+  # The gRPC status code the daemon pairs each tagged code with
+  # (antd/src/error.rs). A tag on any other status code is not trusted.
+  GRPC_STATUS_FOR_ERROR_CODE = {
+    "POINTER_FINAL" => 9,         # FAILED_PRECONDITION
+    "POINTER_FORKED" => 9,        # FAILED_PRECONDITION
+    "CONFLICT" => 10,             # ABORTED
+    "CLOSE_GROUP_SHORTFALL" => 14 # UNAVAILABLE
+  }.freeze
+  private_constant :GRPC_STATUS_FOR_ERROR_CODE
+
+  # The hint that closes a CLOSE_GROUP_SHORTFALL message when a pointer
+  # finalize kept the paid state: "(paid attempt retained...)" at the very
+  # end of the details, as for a retained partial upload.
+  CLOSE_GROUP_RETAINED_TAIL = /\(#{Regexp.escape(PARTIAL_UPLOAD_RETAINED_HINT)}[^()]*\)\z/
+  private_constant :CLOSE_GROUP_RETAINED_TAIL
+
+  # The typed error for a daemon error +code+ that shares its HTTP status (and
+  # gRPC code) with older errors: the 409s POINTER_FINAL, POINTER_FORKED and
+  # CONFLICT, and CLOSE_GROUP_SHORTFALL's 503. nil for any other code, which
+  # keeps the status-based mapping.
+  #
+  # @param code [Object] the daemon's error code
+  # @param message [String]
+  # @param retryable [Boolean] CLOSE_GROUP_SHORTFALL only
+  # @return [AntdError, nil]
+  def self.error_for_code(code, message, retryable: false)
+    case code
+    when "POINTER_FINAL" then PointerFinalError.new(message)
+    when "POINTER_FORKED" then PointerForkedError.new(message)
+    when "CONFLICT" then ConflictError.new(message)
+    when "CLOSE_GROUP_SHORTFALL" then CloseGroupShortfallError.new(message, retryable: retryable)
+    end
+  end
+
+  # The typed error for a gRPC status the daemon tagged with
+  # +x-antd-error-code+ (in the trailing metadata, +GRPC::BadStatus#metadata+),
+  # when the tag agrees with the status code: FAILED_PRECONDITION for
+  # POINTER_FINAL / POINTER_FORKED, ABORTED for CONFLICT, UNAVAILABLE for
+  # CLOSE_GROUP_SHORTFALL. nil for an untagged status, a tag this SDK does not
+  # know, or a tag on another status code; the caller then keeps the
+  # code-based mapping (so an untagged FAILED_PRECONDITION is still a
+  # +PaymentError+).
+  #
+  # @param code [Integer] gRPC status code
+  # @param details [String, nil] the status details as the daemon sent them,
+  #   read for CLOSE_GROUP_SHORTFALL's retained hint
+  # @param message [String] the message for the raised error
+  # @param metadata [Hash, nil] trailing metadata
+  # @return [AntdError, nil]
+  def self.error_for_grpc_metadata(code, details, message, metadata)
+    tag = metadata.is_a?(Hash) ? metadata[ANTD_ERROR_CODE_METADATA] : nil
+    tag = tag.first if tag.is_a?(Array)
+    return nil unless tag.is_a?(String) && GRPC_STATUS_FOR_ERROR_CODE[tag] == code
+
+    error_for_code(tag, message, retryable: CLOSE_GROUP_RETAINED_TAIL.match?(details.to_s))
+  end
+
   # Maps a non-2xx REST response onto a typed error, preferring the body's
   # machine-readable +code+ over the bare HTTP status where they diverge:
   # +PARTIAL_UPLOAD+ arrives as a 502 that would otherwise read as a generic
-  # +NetworkError+. Every other code keeps the status-based mapping of
-  # +error_for_status+. A JSON object body's +error+ field becomes the
-  # message when it is a string; otherwise (non-JSON body, a JSON value that
-  # is not an object, a non-string +error+) the raw body is the message.
+  # +NetworkError+, POINTER_FINAL, POINTER_FORKED and CONFLICT are 409s that
+  # must not read as +AlreadyExistsError+, and CLOSE_GROUP_SHORTFALL is a 503
+  # that must not read as +ServiceUnavailableError+ (see +error_for_code+).
+  # Every other code keeps the status-based mapping of +error_for_status+. A
+  # JSON object body's +error+ field becomes the message when it is a string;
+  # otherwise (non-JSON body, a JSON value that is not an object, a non-string
+  # +error+) the raw body is the message.
   #
   # Never raises on a malformed body: every field is type-checked, not
   # coerced. Only a +code+ that is exactly the string "PARTIAL_UPLOAD"
@@ -264,6 +388,11 @@ module Antd
           retention_known: [true, false].include?(parsed["retryable"])
         )
       end
+
+      # retryable is present, and true, only on a pointer finalize that kept
+      # the paid state; anything else reads as not retained.
+      coded = error_for_code(parsed["code"], message, retryable: parsed["retryable"] == true)
+      return coded if coded
     end
 
     error_for_status(code, message)