antd 0.1.0 → 0.3.0

data/lib/antd/errors.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "json"
+
 module Antd
   # Base error type for all antd errors.
   class AntdError < StandardError
@@ -56,6 +58,357 @@ 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.
+  # How to finish the upload depends on +retryable+ and +retention_known+:
+  #
+  # - +retryable+ (antd >= 0.14.0; implies +retention_known+): the daemon kept
+  #   the paid attempt (payment proofs + unstored chunks) 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+ and not +retryable+: the daemon confirmed nothing was
+  #   retained (a merkle finalize with deliberately unpaid batches).
+  #   Re-preparing the same content skips already-stored chunks, so a retry
+  #   pays only for the missing remainder.
+  # - not +retention_known+: retention is unknown. The error did not say, in
+  #   a form this SDK could read, whether the paid attempt was kept, and 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 the counts and flags come from the structured error body; a
+  # count of the wrong JSON type reads as 0, and +retention_known+ is true
+  # only when the body's +retryable+ is a JSON boolean. Over gRPC they are
+  # parsed best-effort from the status details ("Partial upload: S/T chunks
+  # stored, F failed after retries: <reason> (<hint>)"); only an ABORTED
+  # whose details start with "Partial upload:" is a partial upload.
+  # +retention_known+ is true there only when the details start with the
+  # counts, all three parse, and the details end 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).
+  # Counts that do not parse leave all three zero and both flags false.
+  # Readable counts with a missing, truncated or unrecognised hint keep the
+  # counts, but both flags stay false: retention unknown, not "nothing
+  # retained".
+  #
+  # Subclasses +NetworkError+ because the daemon reports it as a 502: existing
+  # +rescue Antd::NetworkError+ blocks keep catching it, and +status_code+ is
+  # 502 on both transports. Rescue +PartialUploadError+ first to handle it
+  # specifically. See docs/external-signer-flow.md section 6.
+  class PartialUploadError < NetworkError
+    attr_reader :chunks_stored, :chunks_failed, :total_chunks, :retryable, :retention_known
+
+    # @param message [String]
+    # @param chunks_stored [Integer] chunks confirmed stored on the network
+    # @param chunks_failed [Integer] chunks still unstored after retries
+    # @param total_chunks [Integer] chunks in the upload
+    # @param retryable [Boolean] whether the daemon retained the paid attempt
+    # @param retention_known [Boolean] whether the daemon said, in a form this
+    #   SDK could read, whether it retained the paid attempt. +retryable+
+    #   implies it: +retryable: true+ always yields +retention_known == true+.
+    def initialize(message, chunks_stored: 0, chunks_failed: 0, total_chunks: 0, retryable: false,
+                   retention_known: false)
+      @chunks_stored = chunks_stored
+      @chunks_failed = chunks_failed
+      @total_chunks = total_chunks
+      @retryable = retryable
+      @retention_known = (retention_known || retryable) ? true : false
+      super(message)
+    end
+
+    alias retryable? retryable
+    alias retention_known? retention_known
+  end
+
+  # Fixed text every PARTIAL_UPLOAD message from the daemon opens with. Over
+  # gRPC the status carries no structured code, so an ABORTED status is a
+  # partial upload only when its details start with this prefix.
+  PARTIAL_UPLOAD_PREFIX = "Partial upload:"
+
+  # Fixed prefix of the daemon's PARTIAL_UPLOAD message:
+  # "Partial upload: <stored>/<total> chunks stored, <failed> failed".
+  # Anchored with +\A+ (start of input; +^+ would also match after a
+  # newline), so counts quoted later in a garbled message are never read.
+  PARTIAL_UPLOAD_COUNTS = %r{\APartial upload: (\d+)/(\d+) chunks stored, (\d+) failed}
+
+  # The daemon closes every PARTIAL_UPLOAD message with one of two
+  # parenthesised hints (partial_upload_hint in antd/src/error.rs). This one
+  # opens the hint when it kept the paid attempt for a same-upload_id retry.
+  PARTIAL_UPLOAD_RETAINED_HINT = "paid attempt retained"
+
+  # This one opens the hint when it did not. Daemons older than 0.14.0 write
+  # only this one.
+  PARTIAL_UPLOAD_NOT_RETAINED_HINT = "stored chunks persist; re-prepare the same content"
+  private_constant :PARTIAL_UPLOAD_NOT_RETAINED_HINT
+
+  # The hint that closes the message: "(<hint>...)" at the very end. +\z+ is
+  # the end of the input; Ruby's +$+ is the end of a LINE and +\Z+ allows a
+  # trailing newline. A hint quoted inside the failure reason, a truncated
+  # or unclosed tail, or any text after the hint does not match.
+  PARTIAL_UPLOAD_RETENTION_TAIL =
+    /\((#{Regexp.union(PARTIAL_UPLOAD_RETAINED_HINT, PARTIAL_UPLOAD_NOT_RETAINED_HINT).source})[^()]*\)\z/
+  private_constant :PARTIAL_UPLOAD_RETENTION_TAIL
+
+  # Largest count the daemon can send (its counts are u64). Ruby integers are
+  # unbounded, so a larger digit run is treated as a failed conversion.
+  PARTIAL_UPLOAD_COUNT_MAX = 18_446_744_073_709_551_615
+  private_constant :PARTIAL_UPLOAD_COUNT_MAX
+
+  # Whether a gRPC status's details are the daemon's PARTIAL_UPLOAD message.
+  # Anchored: the details must start with +PARTIAL_UPLOAD_PREFIX+. A status
+  # that merely quotes "Partial upload:" further into its text (an upstream
+  # error wrapping one, say) is not a partial upload and must not select the
+  # paid-attempt recovery path with zero counts.
+  #
+  # Pass +GRPC::BadStatus#details+ -- the status message exactly as the
+  # daemon sent it -- not +#message+, which grpc-ruby decorates as
+  # "<code>:<details>" ("10:Partial upload: ...") and so never starts with
+  # the prefix.
+  #
+  # @param details [String, nil] gRPC status details
+  # @return [Boolean]
+  def self.partial_upload_message?(details)
+    details.to_s.start_with?(PARTIAL_UPLOAD_PREFIX)
+  end
+
+  # Recovers the chunk counts and the retention flags from a PARTIAL_UPLOAD
+  # message (over gRPC, the status details). Used for gRPC, where the status
+  # carries no structured detail; REST callers get the body fields instead.
+  #
+  # Conservative: +retention_known+ is true only when the message starts
+  # with the counts pattern ("Partial upload: <stored>/<total> chunks
+  # stored, <failed> failed"), all three counts converted (each at most
+  # u64::MAX, the daemon's count type), and the message ends with one of the
+  # daemon's two hints, "(paid attempt retained...)" or "(stored chunks
+  # persist; re-prepare the same content...)"; +retryable+ is then true only
+  # for the first. On a prefix or pattern miss, or a count out of range, all
+  # three counts are 0 and both flags are false. Readable counts with a
+  # missing, truncated or unrecognised tail, or text after it, keep the
+  # counts but leave both flags false: the daemon's answer on retention was
+  # not read, so retention is unknown, never "nothing retained". A message
+  # the parser cannot fully read never selects the same-upload_id retry, and
+  # never reads as confirmed non-retention.
+  #
+  # @param message [String]
+  # @return [Hash] +:chunks_stored+, +:chunks_failed+, +:total_chunks+,
+  #   +:retryable+, +:retention_known+ -- splat into +PartialUploadError.new+
+  def self.parse_partial_upload_message(message)
+    text = message.to_s
+    m = partial_upload_message?(text) && PARTIAL_UPLOAD_COUNTS.match(text)
+    # The groups are ASCII digit runs, so #to_i is exact; only the range can fail.
+    stored, total, failed = m && [m[1], m[2], m[3]].map(&:to_i)
+    unless m && [stored, total, failed].all? { |n| n <= PARTIAL_UPLOAD_COUNT_MAX }
+      return { chunks_stored: 0, chunks_failed: 0, total_chunks: 0, retryable: false, retention_known: false }
+    end
+
+    # Only the hint that closes the message is the daemon's answer.
+    tail = PARTIAL_UPLOAD_RETENTION_TAIL.match(text)
+    {
+      chunks_stored: stored,
+      chunks_failed: failed,
+      total_chunks: total,
+      retryable: !tail.nil? && tail[1] == PARTIAL_UPLOAD_RETAINED_HINT,
+      retention_known: !tail.nil?
+    }
+  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+, 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"
+  # selects +PartialUploadError+; a count that is not a non-negative JSON
+  # integer reads as 0; +retryable+ is true only for JSON +true+; and
+  # +retention_known+ is true only when +retryable+ is a JSON boolean (absent
+  # on daemons < 0.14.0, +null+ or any other type reads as unknown).
+  #
+  # @param code [Integer] HTTP status
+  # @param body [String, nil] raw response body
+  # @return [AntdError]
+  def self.error_for_response(code, body)
+    message = body.to_s
+    parsed = begin
+      JSON.parse(message)
+    rescue JSON::ParserError
+      nil # use raw body as message
+    end
+    parsed = nil unless parsed.is_a?(Hash)
+
+    if parsed
+      message = parsed["error"] if parsed["error"].is_a?(String)
+      if parsed["code"] == "PARTIAL_UPLOAD"
+        return PartialUploadError.new(
+          message,
+          chunks_stored: body_count(parsed["chunks_stored"]),
+          chunks_failed: body_count(parsed["chunks_failed"]),
+          total_chunks: body_count(parsed["total_chunks"]),
+          retryable: parsed["retryable"] == true,
+          # Known only when the daemon sent the flag as a JSON boolean. Absent
+          # (daemons < 0.14.0), null or any other type -> unknown: the daemon
+          # may still hold the paid attempt, so this is not a re-prepare signal.
+          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)
+  end
+
+  # A chunk count from a PARTIAL_UPLOAD body: a non-negative JSON integer is
+  # taken as is; anything else (absent, null, string, float, boolean, array,
+  # object, negative) reads as 0 rather than raising or being coerced.
+  #
+  # @param value [Object] parsed JSON value
+  # @return [Integer]
+  def self.body_count(value)
+    value.is_a?(Integer) && value >= 0 ? value : 0
+  end
+  private_class_method :body_count
+
   # Returns the appropriate error type for an HTTP status code.
   def self.error_for_status(code, message)
     case code

data/lib/antd/grpc_client.rb

@@ -17,6 +17,8 @@ require_relative "v1/chunks_services_pb"
 require_relative "v1/files_services_pb"
 require_relative "v1/upload_services_pb"
 require_relative "v1/wallet_services_pb"
+require_relative "v1/pointers_services_pb"
+require "base64"
 
 module Antd
   DEFAULT_GRPC_TARGET = "localhost:50051"
@@ -47,6 +49,7 @@ module Antd
       @file_stub   = Antd::V1::FileService::Stub.new(target, :this_channel_is_insecure)
       @upload_stub = Antd::V1::UploadService::Stub.new(target, :this_channel_is_insecure)
       @wallet_stub = Antd::V1::WalletService::Stub.new(target, :this_channel_is_insecure)
+      @pointer_stub = Antd::V1::PointerService::Stub.new(target, :this_channel_is_insecure)
     end
 
     # --- Health ---
@@ -324,6 +327,16 @@ module Antd
     # @param upload_id [String]
     # @param tx_hashes [Hash<String, String>]
     # @return [String] hex chunk address
+    # @raise [PartialUploadError] when some chunks stored and others did not
+    #   (gRPC ABORTED, details prefixed +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)
       req = Antd::V1::FinalizeChunkRequest.new(
         upload_id: upload_id,
@@ -378,6 +391,16 @@ module Antd
     # @param upload_id [String]
     # @param tx_hashes [Hash<String, String>]
     # @return [FinalizeUploadResult]
+    # @raise [PartialUploadError] when some chunks stored and others did not
+    #   (gRPC ABORTED, details prefixed +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)
       req = Antd::V1::FinalizeUploadRequest.new(
         upload_id: upload_id,
@@ -399,6 +422,16 @@ module Antd
     # @param winner_pool_hash [String]
     # @param store_data_map [Boolean]
     # @return [FinalizeUploadResult]
+    # @raise [PartialUploadError] when some chunks stored and others did not
+    #   (gRPC ABORTED, details prefixed +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)
       req = Antd::V1::FinalizeUploadRequest.new(
         upload_id: upload_id,
@@ -438,8 +471,183 @@ module Antd
       resp.approved
     end
 
+    # --- Pointers ---
+    #
+    # The same methods, models and errors as the REST +Client+ (see there),
+    # over PointerService. The pointer errors share gRPC status codes with
+    # older ones, so the daemon names them in the +x-antd-error-code+
+    # trailer, which +grpc_call+ reads (see +Antd.error_for_grpc_metadata+).
+    # Unset optionals arrive as "" or an absent message and read as nil, as
+    # REST's nulls do. Every write pays: do not retry +pointer_create+,
+    # +pointer_update+, +pointer_transfer+ or +pointer_finalize+
+    # automatically.
+
+    # Mirrors +Client#pointer_keys+.
+    # @return [Array<String>]
+    def pointer_keys
+      resp = grpc_call { @pointer_stub.list_keys(Antd::V1::ListPointerKeysRequest.new) }
+      resp.keys.map(&:address)
+    end
+
+    # Mirrors +Client#pointer_create+. Pays; do not retry automatically.
+    # @return [PointerWriteResult]
+    def pointer_create(owner, target, kind: nil)
+      req = Antd::V1::PointerWriteRequest.new(owner: owner, target: target, kind: kind.to_s)
+      pointer_write_result(grpc_call { @pointer_stub.create(req) })
+    end
+
+    # Mirrors +Client#pointer_update+. Pays; do not retry automatically.
+    # @return [PointerWriteResult]
+    def pointer_update(owner, target, kind: nil)
+      req = Antd::V1::PointerWriteRequest.new(owner: owner, target: target, kind: kind.to_s)
+      pointer_write_result(grpc_call { @pointer_stub.update(req) })
+    end
+
+    # Mirrors +Client#pointer_transfer+. Pays; do not retry automatically.
+    # @return [PointerTransferResult]
+    def pointer_transfer(owner, recipient)
+      req = Antd::V1::PointerTransferRequest.new(owner: owner, recipient: recipient)
+      resp = grpc_call { @pointer_stub.transfer(req) }
+      PointerTransferResult.new(
+        address: resp.address,
+        state_id: resp.state_id,
+        finality: resp.finality.nil? ? nil : pointer_finality_from(resp.finality),
+        finality_error: presence(resp.finality_error)
+      )
+    end
+
+    # Mirrors +Client#pointer_get+.
+    # @return [PointerRecord]
+    def pointer_get(address)
+      resp = grpc_call { @pointer_stub.get(Antd::V1::GetPointerRequest.new(address: address)) }
+      PointerRecord.new(
+        address: resp.address,
+        owner: resp.owner,
+        counter: Antd.parse_pointer_counter("counter", resp.counter),
+        kind: resp.kind,
+        kind_tag: resp.kind_tag,
+        target: resp.target,
+        state_id: resp.state_id,
+        is_final: resp.is_final,
+        transferred_to: presence(resp.transferred_to)
+      )
+    end
+
+    # Mirrors +Client#pointer_resolve+.
+    # @return [PointerTarget]
+    def pointer_resolve(address)
+      resp = grpc_call { @pointer_stub.resolve(Antd::V1::ResolvePointerRequest.new(address: address)) }
+      PointerTarget.new(kind: resp.kind, kind_tag: resp.kind_tag, target: resp.target)
+    end
+
+    # Mirrors +Client#pointer_finality+.
+    # @return [PointerFinality]
+    def pointer_finality(address)
+      resp = grpc_call { @pointer_stub.finality(Antd::V1::PointerFinalityRequest.new(address: address)) }
+      pointer_finality_from(resp)
+    end
+
+    # Mirrors +Client#pointer_controller+.
+    # @return [PointerController]
+    def pointer_controller(address)
+      resp = grpc_call { @pointer_stub.controller(Antd::V1::PointerControllerRequest.new(address: address)) }
+      PointerController.new(pointer: resp.pointer, transfers: resp.transfers.to_a, frozen: resp.frozen)
+    end
+
+    # Mirrors +Client#pointer_prepare+.
+    # @return [PointerPrepareResult]
+    def pointer_prepare(owner, op, target: nil, kind: nil, recipient: nil, include_signed_quotes: false)
+      req = Antd::V1::PreparePointerRequest.new(
+        owner: owner,
+        op: op.to_s,
+        target: target.to_s,
+        kind: kind.to_s,
+        recipient: recipient.to_s,
+        include_signed_quotes: include_signed_quotes ? true : false
+      )
+      resp = grpc_call { @pointer_stub.prepare(req) }
+      PointerPrepareResult.new(
+        upload_id: resp.upload_id,
+        op: resp.op,
+        address: resp.address,
+        state_id: resp.state_id,
+        counter: Antd.parse_pointer_counter("counter", resp.counter),
+        payment_type: resp.payment_type,
+        payments: resp.payments.map do |p|
+          PaymentInfo.new(quote_hash: p.quote_hash, rewards_address: p.rewards_address, amount: p.amount)
+        end,
+        total_amount: resp.total_amount,
+        payment_vault_address: resp.payment_vault_address,
+        payment_token_address: resp.payment_token_address,
+        rpc_url: resp.rpc_url,
+        # Bytes on the wire; base64 here, the same form REST returns.
+        signed_quotes: resp.signed_quotes.map do |q|
+          SignedQuoteEntry.new(
+            quote_hash: q.quote_hash,
+            quote: Base64.strict_encode64(q.quote),
+            commitment_sidecar: q.commitment_sidecar.empty? ? nil : Base64.strict_encode64(q.commitment_sidecar)
+          )
+        end
+      )
+    end
+
+    # Mirrors +Client#pointer_finalize+. A +CloseGroupShortfallError+ with
+    # +retryable+ means the daemon kept the paid state: repeat the call with
+    # the same +upload_id+.
+    # @return [PointerFinalizeResult]
+    def pointer_finalize(upload_id, tx_hashes)
+      req = Antd::V1::FinalizePointerRequest.new(upload_id: upload_id, tx_hashes: tx_hashes)
+      resp = grpc_call { @pointer_stub.finalize(req) }
+      PointerFinalizeResult.new(
+        address: resp.address,
+        state_id: resp.state_id,
+        counter: Antd.parse_pointer_counter("counter", resp.counter),
+        finality: resp.finality.nil? ? nil : pointer_finality_from(resp.finality)
+      )
+    end
+
     private
 
+    def pointer_write_result(resp)
+      PointerWriteResult.new(
+        address: resp.address,
+        state_id: resp.state_id,
+        counter: Antd.parse_pointer_counter("counter", resp.counter)
+      )
+    end
+
+    # Converts the proto finality, where an unset counter or transferred_to is
+    # "" and an unset state or majority an absent message: each reads as nil.
+    def pointer_finality_from(f)
+      PointerFinality.new(
+        address: f.address,
+        group: f.group,
+        answered: f.answered,
+        status: f.status,
+        counter: f.counter.empty? ? nil : Antd.parse_pointer_counter("finality counter", f.counter),
+        state: f.state.nil? ? nil : pointer_final_state_from(f.state),
+        states: f.states.map { |s| pointer_final_state_from(s) },
+        majority: f.majority.nil? ? nil : pointer_final_state_from(f.majority),
+        transferred_to: presence(f.transferred_to)
+      )
+    end
+
+    def pointer_final_state_from(s)
+      PointerFinalState.new(
+        state_id: s.state_id,
+        kind: s.kind,
+        kind_tag: s.kind_tag,
+        target: s.target,
+        holders: s.holders,
+        transferred_to: presence(s.transferred_to)
+      )
+    end
+
+    # A proto string, or nil when unset (empty).
+    def presence(value)
+      value.nil? || value.empty? ? nil : value
+    end
+
     # Drives a +return_op: true+ server-streaming call, yielding +DownloadFrame+s.
     # The byte denominator is surfaced first as a leading +DownloadFrame+ (its
     # +meta+ set), read from the response's +x-content-length+ initial metadata;
@@ -520,14 +728,31 @@ module Antd
         payment_type: resp.payment_type,
         depth: is_merkle ? resp.depth : nil,
         pool_commitments: pool_commitments,
-        merkle_payment_timestamp: is_merkle ? resp.merkle_payment_timestamp.to_i : nil
+        merkle_payment_timestamp: is_merkle ? resp.merkle_payment_timestamp.to_i : nil,
+        # Already-stored preflight (parity with REST): the external signer
+        # pays for total_chunks - already_stored_count chunks.
+        total_chunks: resp.total_chunks,
+        already_stored_count: resp.already_stored_count
       )
     end
 
 
     # Executes a gRPC call and translates errors to Antd error types.
+    #
+    # The daemon's +x-antd-error-code+ trailer comes first: where it names a
+    # code that shares its gRPC status with older errors (POINTER_FINAL,
+    # POINTER_FORKED, CONFLICT, CLOSE_GROUP_SHORTFALL) and agrees with the
+    # status code, it selects the typed error. Anything else is re-raised to
+    # the status-code mapping below.
     def grpc_call
-      yield
+      begin
+        yield
+      rescue GRPC::BadStatus => e
+        tagged = Antd.error_for_grpc_metadata(e.code, e.details, e.message, e.metadata)
+        raise tagged unless tagged.nil?
+
+        raise
+      end
     rescue GRPC::InvalidArgument => e
       raise BadRequestError, e.message
     rescue GRPC::NotFound => e
@@ -542,6 +767,24 @@ module Antd
       raise NetworkError, e.message
     rescue GRPC::FailedPrecondition => e
       raise PaymentError, e.message
+    rescue GRPC::Aborted => e
+      # PARTIAL_UPLOAD: some chunks stored, some still unstored after
+      # retries. The daemon's status message always opens with "Partial
+      # upload:", so only an ABORTED whose details *start* with it becomes
+      # the typed error. Any other ABORTED -- including one that merely
+      # quotes the marker further in -- keeps the generic mapping instead of
+      # masquerading as a partial upload with zero counts. Gate and parse on
+      # +e.details+ (the message as the daemon sent it), not +e.message+,
+      # which grpc-ruby decorates as "10:<details>". The counts and the
+      # daemon's closing retention hint ride that text over gRPC (no
+      # structured detail yet), so parse them best-effort to match the REST
+      # client's typed error: retention is known only when the counts parse
+      # and the text ends with one of the daemon's two hints (see
+      # Antd.parse_partial_upload_message). The raised message stays
+      # +e.message+, like every other branch.
+      raise AntdError.new(e.message, status_code: e.code) unless Antd.partial_upload_message?(e.details)
+
+      raise PartialUploadError.new(e.message, **Antd.parse_partial_upload_message(e.details))
     rescue GRPC::BadStatus => e
       raise AntdError.new(e.message, status_code: e.code)
     end