antd 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 44a5ae69094c720b34c8d440aa9072ab3d83e192fc790351c9d08ab8d4ef6f8f
-  data.tar.gz: '0329577dd7ac059a32b8f6bd47369e0452d3f13679f8c37e5da245359772b339'
+  metadata.gz: ab6786553e76394691c28a2968384dd279738e876ecf961e74a0b7b46904cc0e
+  data.tar.gz: a04836fdba38a5457a3cfda27c3adde84bc8175a87dcd1c58e719fb315cc1f0a
 SHA512:
-  metadata.gz: d36cc92042a95ea03a429f5a706fe208d5b4c9c9ff030bcaf7fe72014e7e50feb15a0dd8b26426183de8581d9a90357bdc326dac959ca7ca590a3efaf5726914
-  data.tar.gz: ec4d4aadcc549fde1a6214030934aedefe9ca948dc4c72177bfa82d237c85819eb4edf0890e8940444d63113208760fa222850ce423a9d9a77e1e5fd15a06d0b
+  metadata.gz: '0806f4881413dd24b52a385319ee23ca30de479dea639b54ef0088bd31f8f0cdba73c0d458843082f697e6a92a3bb4c1f5c34dd77532d38d8032dcb4845f3c78'
+  data.tar.gz: 12fffe89716557c9dc2716a99f5f8b39a4958251387050f8828f45ff69628e2350e5aa6dc370f55a89d3abfc06fbb214770bf9cd1c31e516e794fc09daaf9fd4

data/README.md

@@ -87,7 +87,14 @@ 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`).
 
 > **Note:** Wallet operations (address, balance, approve) and payment_mode are available via REST only.
 
@@ -172,6 +179,82 @@ 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` |
+
+### 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.
 
 ## Examples
 
@@ -182,3 +265,4 @@ 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

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,
@@ -483,6 +513,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 +539,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 +551,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 +577,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 +619,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 = +""

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,228 @@ module Antd
     def initialize(message) = super(message, status_code: 503)
   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
+
+  # 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.
+  #
+  # 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
+    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

@@ -324,6 +324,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 +388,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 +419,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,
@@ -520,7 +550,11 @@ 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
 
@@ -542,6 +576,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

data/lib/antd/v1/chunks_pb.rb

@@ -7,7 +7,7 @@ require 'google/protobuf'
 require 'antd/v1/common_pb'
 
 
-descriptor_data = "\n\x14\x61ntd/v1/chunks.proto\x12\x07\x61ntd.v1\x1a\x14\x61ntd/v1/common.proto\"\"\n\x0fGetChunkRequest\x12\x0f\n\x07\x61\x64\x64ress\x18\x01 \x01(\t\" \n\x10GetChunkResponse\x12\x0c\n\x04\x64\x61ta\x18\x01 \x01(\x0c\"\x1f\n\x0fPutChunkRequest\x12\x0c\n\x04\x64\x61ta\x18\x01 \x01(\x0c\"@\n\x10PutChunkResponse\x12\x1b\n\x04\x63ost\x18\x01 \x01(\x0b\x32\r.antd.v1.Cost\x12\x0f\n\x07\x61\x64\x64ress\x18\x02 \x01(\t\"#\n\x13PrepareChunkRequest\x12\x0c\n\x04\x64\x61ta\x18\x01 \x01(\x0c\"\xf6\x01\n\x14PrepareChunkResponse\x12\x0f\n\x07\x61\x64\x64ress\x18\x01 \x01(\t\x12\x16\n\x0e\x61lready_stored\x18\x02 \x01(\x08\x12\x11\n\tupload_id\x18\x03 \x01(\t\x12\x14\n\x0cpayment_type\x18\x04 \x01(\t\x12\'\n\x08payments\x18\x05 \x03(\x0b\x32\x15.antd.v1.PaymentEntry\x12\x14\n\x0ctotal_amount\x18\x06 \x01(\t\x12\x1d\n\x15payment_vault_address\x18\x07 \x01(\t\x12\x1d\n\x15payment_token_address\x18\x08 \x01(\t\x12\x0f\n\x07rpc_url\x18\t \x01(\t\"\x9a\x01\n\x14\x46inalizeChunkRequest\x12\x11\n\tupload_id\x18\x01 \x01(\t\x12>\n\ttx_hashes\x18\x02 \x03(\x0b\x32+.antd.v1.FinalizeChunkRequest.TxHashesEntry\x1a/\n\rTxHashesEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12\r\n\x05value\x18\x02 \x01(\t:\x02\x38\x01\"(\n\x15\x46inalizeChunkResponse\x12\x0f\n\x07\x61\x64\x64ress\x18\x01 \x01(\t2\xa3\x02\n\x0c\x43hunkService\x12:\n\x03Get\x12\x18.antd.v1.GetChunkRequest\x1a\x19.antd.v1.GetChunkResponse\x12:\n\x03Put\x12\x18.antd.v1.PutChunkRequest\x1a\x19.antd.v1.PutChunkResponse\x12K\n\x0cPrepareChunk\x12\x1c.antd.v1.PrepareChunkRequest\x1a\x1d.antd.v1.PrepareChunkResponse\x12N\n\rFinalizeChunk\x12\x1d.antd.v1.FinalizeChunkRequest\x1a\x1e.antd.v1.FinalizeChunkResponseBDZ8github.com/WithAutonomi/ant-sdk/antd-go/proto/antd/v1;v1\xaa\x02\x07\x41ntd.V1b\x06proto3"
+descriptor_data = "\n\x14\x61ntd/v1/chunks.proto\x12\x07\x61ntd.v1\x1a\x14\x61ntd/v1/common.proto\"\"\n\x0fGetChunkRequest\x12\x0f\n\x07\x61\x64\x64ress\x18\x01 \x01(\t\" \n\x10GetChunkResponse\x12\x0c\n\x04\x64\x61ta\x18\x01 \x01(\x0c\"\x1f\n\x0fPutChunkRequest\x12\x0c\n\x04\x64\x61ta\x18\x01 \x01(\x0c\"@\n\x10PutChunkResponse\x12\x1b\n\x04\x63ost\x18\x01 \x01(\x0b\x32\r.antd.v1.Cost\x12\x0f\n\x07\x61\x64\x64ress\x18\x02 \x01(\t\"B\n\x13PrepareChunkRequest\x12\x0c\n\x04\x64\x61ta\x18\x01 \x01(\x0c\x12\x1d\n\x15include_signed_quotes\x18\x02 \x01(\x08\"\xa8\x02\n\x14PrepareChunkResponse\x12\x0f\n\x07\x61\x64\x64ress\x18\x01 \x01(\t\x12\x16\n\x0e\x61lready_stored\x18\x02 \x01(\x08\x12\x11\n\tupload_id\x18\x03 \x01(\t\x12\x14\n\x0cpayment_type\x18\x04 \x01(\t\x12\'\n\x08payments\x18\x05 \x03(\x0b\x32\x15.antd.v1.PaymentEntry\x12\x14\n\x0ctotal_amount\x18\x06 \x01(\t\x12\x1d\n\x15payment_vault_address\x18\x07 \x01(\t\x12\x1d\n\x15payment_token_address\x18\x08 \x01(\t\x12\x0f\n\x07rpc_url\x18\t \x01(\t\x12\x30\n\rsigned_quotes\x18\n \x03(\x0b\x32\x19.antd.v1.SignedQuoteEntry\"\x9a\x01\n\x14\x46inalizeChunkRequest\x12\x11\n\tupload_id\x18\x01 \x01(\t\x12>\n\ttx_hashes\x18\x02 \x03(\x0b\x32+.antd.v1.FinalizeChunkRequest.TxHashesEntry\x1a/\n\rTxHashesEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12\r\n\x05value\x18\x02 \x01(\t:\x02\x38\x01\"(\n\x15\x46inalizeChunkResponse\x12\x0f\n\x07\x61\x64\x64ress\x18\x01 \x01(\t2\xa3\x02\n\x0c\x43hunkService\x12:\n\x03Get\x12\x18.antd.v1.GetChunkRequest\x1a\x19.antd.v1.GetChunkResponse\x12:\n\x03Put\x12\x18.antd.v1.PutChunkRequest\x1a\x19.antd.v1.PutChunkResponse\x12K\n\x0cPrepareChunk\x12\x1c.antd.v1.PrepareChunkRequest\x1a\x1d.antd.v1.PrepareChunkResponse\x12N\n\rFinalizeChunk\x12\x1d.antd.v1.FinalizeChunkRequest\x1a\x1e.antd.v1.FinalizeChunkResponseBDZ8github.com/WithAutonomi/ant-sdk/antd-go/proto/antd/v1;v1\xaa\x02\x07\x41ntd.V1b\x06proto3"
 
 pool = ::Google::Protobuf::DescriptorPool.generated_pool
 pool.add_serialized_file(descriptor_data)

data/lib/antd/v1/common_pb.rb

@@ -5,7 +5,7 @@
 require 'google/protobuf'
 
 
-descriptor_data = "\n\x14\x61ntd/v1/common.proto\x12\x07\x61ntd.v1\"y\n\x04\x43ost\x12\x13\n\x0b\x61tto_tokens\x18\x01 \x01(\t\x12\x11\n\tfile_size\x18\x02 \x01(\x04\x12\x13\n\x0b\x63hunk_count\x18\x03 \x01(\r\x12\x1e\n\x16\x65stimated_gas_cost_wei\x18\x04 \x01(\t\x12\x14\n\x0cpayment_mode\x18\x05 \x01(\t\"\x16\n\x07\x41\x64\x64ress\x12\x0b\n\x03hex\x18\x01 \x01(\t\"\x1d\n\x0ePublicKeyProto\x12\x0b\n\x03hex\x18\x01 \x01(\t\"\x1d\n\x0eSecretKeyProto\x12\x0b\n\x03hex\x18\x01 \x01(\t\"K\n\x0cPaymentEntry\x12\x12\n\nquote_hash\x18\x01 \x01(\t\x12\x17\n\x0frewards_address\x18\x02 \x01(\t\x12\x0e\n\x06\x61mount\x18\x03 \x01(\tBDZ8github.com/WithAutonomi/ant-sdk/antd-go/proto/antd/v1;v1\xaa\x02\x07\x41ntd.V1b\x06proto3"
+descriptor_data = "\n\x14\x61ntd/v1/common.proto\x12\x07\x61ntd.v1\"y\n\x04\x43ost\x12\x13\n\x0b\x61tto_tokens\x18\x01 \x01(\t\x12\x11\n\tfile_size\x18\x02 \x01(\x04\x12\x13\n\x0b\x63hunk_count\x18\x03 \x01(\r\x12\x1e\n\x16\x65stimated_gas_cost_wei\x18\x04 \x01(\t\x12\x14\n\x0cpayment_mode\x18\x05 \x01(\t\"\x16\n\x07\x41\x64\x64ress\x12\x0b\n\x03hex\x18\x01 \x01(\t\"\x1d\n\x0ePublicKeyProto\x12\x0b\n\x03hex\x18\x01 \x01(\t\"\x1d\n\x0eSecretKeyProto\x12\x0b\n\x03hex\x18\x01 \x01(\t\"K\n\x0cPaymentEntry\x12\x12\n\nquote_hash\x18\x01 \x01(\t\x12\x17\n\x0frewards_address\x18\x02 \x01(\t\x12\x0e\n\x06\x61mount\x18\x03 \x01(\t\"Q\n\x10SignedQuoteEntry\x12\x12\n\nquote_hash\x18\x01 \x01(\t\x12\r\n\x05quote\x18\x02 \x01(\x0c\x12\x1a\n\x12\x63ommitment_sidecar\x18\x03 \x01(\x0c\x42\x44Z8github.com/WithAutonomi/ant-sdk/antd-go/proto/antd/v1;v1\xaa\x02\x07\x41ntd.V1b\x06proto3"
 
 pool = ::Google::Protobuf::DescriptorPool.generated_pool
 pool.add_serialized_file(descriptor_data)
@@ -17,5 +17,6 @@ module Antd
     PublicKeyProto = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("antd.v1.PublicKeyProto").msgclass
     SecretKeyProto = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("antd.v1.SecretKeyProto").msgclass
     PaymentEntry = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("antd.v1.PaymentEntry").msgclass
+    SignedQuoteEntry = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("antd.v1.SignedQuoteEntry").msgclass
   end
 end

data/lib/antd/v1/health_pb.rb

@@ -5,7 +5,7 @@
 require 'google/protobuf'
 
 
-descriptor_data = "\n\x14\x61ntd/v1/health.proto\x12\x07\x61ntd.v1\"\x14\n\x12HealthCheckRequest\"\xc8\x01\n\x13HealthCheckResponse\x12\x0e\n\x06status\x18\x01 \x01(\t\x12\x0f\n\x07network\x18\x02 \x01(\t\x12\x0f\n\x07version\x18\x03 \x01(\t\x12\x13\n\x0b\x65vm_network\x18\x04 \x01(\t\x12\x16\n\x0euptime_seconds\x18\x05 \x01(\x04\x12\x14\n\x0c\x62uild_commit\x18\x06 \x01(\t\x12\x1d\n\x15payment_token_address\x18\x07 \x01(\t\x12\x1d\n\x15payment_vault_address\x18\x08 \x01(\t2S\n\rHealthService\x12\x42\n\x05\x43heck\x12\x1b.antd.v1.HealthCheckRequest\x1a\x1c.antd.v1.HealthCheckResponseBDZ8github.com/WithAutonomi/ant-sdk/antd-go/proto/antd/v1;v1\xaa\x02\x07\x41ntd.V1b\x06proto3"
+descriptor_data = "\n\x14\x61ntd/v1/health.proto\x12\x07\x61ntd.v1\"\x14\n\x12HealthCheckRequest\"\xf1\x02\n\x13HealthCheckResponse\x12\x0e\n\x06status\x18\x01 \x01(\t\x12\x0f\n\x07network\x18\x02 \x01(\t\x12\x0f\n\x07version\x18\x03 \x01(\t\x12\x13\n\x0b\x65vm_network\x18\x04 \x01(\t\x12\x16\n\x0euptime_seconds\x18\x05 \x01(\x04\x12\x14\n\x0c\x62uild_commit\x18\x06 \x01(\t\x12\x1d\n\x15payment_token_address\x18\x07 \x01(\t\x12\x1d\n\x15payment_vault_address\x18\x08 \x01(\t\x12\x13\n\x0bwrite_ready\x18\t \x01(\x08\x12\x17\n\x0f\x63onnected_peers\x18\n \x01(\r\x12\x1a\n\x12routing_table_size\x18\x0b \x01(\r\x12\x1d\n\x15rebootstrap_threshold\x18\x0c \x01(\r\x12#\n\x16last_store_ok_secs_ago\x18\r \x01(\x04H\x00\x88\x01\x01\x42\x19\n\x17_last_store_ok_secs_ago2S\n\rHealthService\x12\x42\n\x05\x43heck\x12\x1b.antd.v1.HealthCheckRequest\x1a\x1c.antd.v1.HealthCheckResponseBDZ8github.com/WithAutonomi/ant-sdk/antd-go/proto/antd/v1;v1\xaa\x02\x07\x41ntd.V1b\x06proto3"
 
 pool = ::Google::Protobuf::DescriptorPool.generated_pool
 pool.add_serialized_file(descriptor_data)

data/lib/antd/v1/upload_pb.rb

@@ -7,7 +7,7 @@ require 'google/protobuf'
 require 'antd/v1/common_pb'
 
 
-descriptor_data = "\n\x14\x61ntd/v1/upload.proto\x12\x07\x61ntd.v1\x1a\x14\x61ntd/v1/common.proto\"<\n\x18PrepareFileUploadRequest\x12\x0c\n\x04path\x18\x01 \x01(\t\x12\x12\n\nvisibility\x18\x02 \x01(\t\"<\n\x18PrepareDataUploadRequest\x12\x0c\n\x04\x64\x61ta\x18\x01 \x01(\x0c\x12\x12\n\nvisibility\x18\x02 \x01(\t\"\xb7\x02\n\x15PrepareUploadResponse\x12\x11\n\tupload_id\x18\x01 \x01(\t\x12\x14\n\x0cpayment_type\x18\x02 \x01(\t\x12\'\n\x08payments\x18\x03 \x03(\x0b\x32\x15.antd.v1.PaymentEntry\x12\r\n\x05\x64\x65pth\x18\x04 \x01(\r\x12\x36\n\x10pool_commitments\x18\x05 \x03(\x0b\x32\x1c.antd.v1.PoolCommitmentEntry\x12 \n\x18merkle_payment_timestamp\x18\x06 \x01(\x04\x12\x14\n\x0ctotal_amount\x18\x07 \x01(\t\x12\x1d\n\x15payment_vault_address\x18\x08 \x01(\t\x12\x1d\n\x15payment_token_address\x18\t \x01(\t\x12\x0f\n\x07rpc_url\x18\n \x01(\t\"Y\n\x13PoolCommitmentEntry\x12\x11\n\tpool_hash\x18\x01 \x01(\t\x12/\n\ncandidates\x18\x02 \x03(\x0b\x32\x1b.antd.v1.CandidateNodeEntry\"=\n\x12\x43\x61ndidateNodeEntry\x12\x17\n\x0frewards_address\x18\x01 \x01(\t\x12\x0e\n\x06\x61mount\x18\x02 \x01(\t\"\xce\x01\n\x15\x46inalizeUploadRequest\x12\x11\n\tupload_id\x18\x01 \x01(\t\x12?\n\ttx_hashes\x18\x02 \x03(\x0b\x32,.antd.v1.FinalizeUploadRequest.TxHashesEntry\x12\x18\n\x10winner_pool_hash\x18\x03 \x01(\t\x12\x16\n\x0estore_data_map\x18\x04 \x01(\x08\x1a/\n\rTxHashesEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12\r\n\x05value\x18\x02 \x01(\t:\x02\x38\x01\"l\n\x16\x46inalizeUploadResponse\x12\x10\n\x08\x64\x61ta_map\x18\x01 \x01(\t\x12\x0f\n\x07\x61\x64\x64ress\x18\x02 \x01(\t\x12\x18\n\x10\x64\x61ta_map_address\x18\x03 \x01(\t\x12\x15\n\rchunks_stored\x18\x04 \x01(\x04\x32\x92\x02\n\rUploadService\x12V\n\x11PrepareFileUpload\x12!.antd.v1.PrepareFileUploadRequest\x1a\x1e.antd.v1.PrepareUploadResponse\x12V\n\x11PrepareDataUpload\x12!.antd.v1.PrepareDataUploadRequest\x1a\x1e.antd.v1.PrepareUploadResponse\x12Q\n\x0e\x46inalizeUpload\x12\x1e.antd.v1.FinalizeUploadRequest\x1a\x1f.antd.v1.FinalizeUploadResponseBDZ8github.com/WithAutonomi/ant-sdk/antd-go/proto/antd/v1;v1\xaa\x02\x07\x41ntd.V1b\x06proto3"
+descriptor_data = "\n\x14\x61ntd/v1/upload.proto\x12\x07\x61ntd.v1\x1a\x14\x61ntd/v1/common.proto\"[\n\x18PrepareFileUploadRequest\x12\x0c\n\x04path\x18\x01 \x01(\t\x12\x12\n\nvisibility\x18\x02 \x01(\t\x12\x1d\n\x15include_signed_quotes\x18\x03 \x01(\x08\"[\n\x18PrepareDataUploadRequest\x12\x0c\n\x04\x64\x61ta\x18\x01 \x01(\x0c\x12\x12\n\nvisibility\x18\x02 \x01(\t\x12\x1d\n\x15include_signed_quotes\x18\x03 \x01(\x08\"\xd0\x03\n\x15PrepareUploadResponse\x12\x11\n\tupload_id\x18\x01 \x01(\t\x12\x14\n\x0cpayment_type\x18\x02 \x01(\t\x12\'\n\x08payments\x18\x03 \x03(\x0b\x32\x15.antd.v1.PaymentEntry\x12\r\n\x05\x64\x65pth\x18\x04 \x01(\r\x12\x36\n\x10pool_commitments\x18\x05 \x03(\x0b\x32\x1c.antd.v1.PoolCommitmentEntry\x12 \n\x18merkle_payment_timestamp\x18\x06 \x01(\x04\x12\x31\n\x0emerkle_batches\x18\x0b \x03(\x0b\x32\x19.antd.v1.MerkleBatchEntry\x12\x14\n\x0ctotal_amount\x18\x07 \x01(\t\x12\x1d\n\x15payment_vault_address\x18\x08 \x01(\t\x12\x1d\n\x15payment_token_address\x18\t \x01(\t\x12\x0f\n\x07rpc_url\x18\n \x01(\t\x12\x30\n\rsigned_quotes\x18\x0c \x03(\x0b\x32\x19.antd.v1.SignedQuoteEntry\x12\x14\n\x0ctotal_chunks\x18\r \x01(\x04\x12\x1c\n\x14\x61lready_stored_count\x18\x0e \x01(\x04\"{\n\x10MerkleBatchEntry\x12\r\n\x05\x64\x65pth\x18\x01 \x01(\r\x12\x36\n\x10pool_commitments\x18\x02 \x03(\x0b\x32\x1c.antd.v1.PoolCommitmentEntry\x12 \n\x18merkle_payment_timestamp\x18\x03 \x01(\x04\"Y\n\x13PoolCommitmentEntry\x12\x11\n\tpool_hash\x18\x01 \x01(\t\x12/\n\ncandidates\x18\x02 \x03(\x0b\x32\x1b.antd.v1.CandidateNodeEntry\"=\n\x12\x43\x61ndidateNodeEntry\x12\x17\n\x0frewards_address\x18\x01 \x01(\t\x12\x0e\n\x06\x61mount\x18\x02 \x01(\t\"\xea\x01\n\x15\x46inalizeUploadRequest\x12\x11\n\tupload_id\x18\x01 \x01(\t\x12?\n\ttx_hashes\x18\x02 \x03(\x0b\x32,.antd.v1.FinalizeUploadRequest.TxHashesEntry\x12\x18\n\x10winner_pool_hash\x18\x03 \x01(\t\x12\x1a\n\x12winner_pool_hashes\x18\x05 \x03(\t\x12\x16\n\x0estore_data_map\x18\x04 \x01(\x08\x1a/\n\rTxHashesEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12\r\n\x05value\x18\x02 \x01(\t:\x02\x38\x01\"l\n\x16\x46inalizeUploadResponse\x12\x10\n\x08\x64\x61ta_map\x18\x01 \x01(\t\x12\x0f\n\x07\x61\x64\x64ress\x18\x02 \x01(\t\x12\x18\n\x10\x64\x61ta_map_address\x18\x03 \x01(\t\x12\x15\n\rchunks_stored\x18\x04 \x01(\x04\x32\x92\x02\n\rUploadService\x12V\n\x11PrepareFileUpload\x12!.antd.v1.PrepareFileUploadRequest\x1a\x1e.antd.v1.PrepareUploadResponse\x12V\n\x11PrepareDataUpload\x12!.antd.v1.PrepareDataUploadRequest\x1a\x1e.antd.v1.PrepareUploadResponse\x12Q\n\x0e\x46inalizeUpload\x12\x1e.antd.v1.FinalizeUploadRequest\x1a\x1f.antd.v1.FinalizeUploadResponseBDZ8github.com/WithAutonomi/ant-sdk/antd-go/proto/antd/v1;v1\xaa\x02\x07\x41ntd.V1b\x06proto3"
 
 pool = ::Google::Protobuf::DescriptorPool.generated_pool
 pool.add_serialized_file(descriptor_data)
@@ -17,6 +17,7 @@ module Antd
     PrepareFileUploadRequest = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("antd.v1.PrepareFileUploadRequest").msgclass
     PrepareDataUploadRequest = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("antd.v1.PrepareDataUploadRequest").msgclass
     PrepareUploadResponse = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("antd.v1.PrepareUploadResponse").msgclass
+    MerkleBatchEntry = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("antd.v1.MerkleBatchEntry").msgclass
     PoolCommitmentEntry = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("antd.v1.PoolCommitmentEntry").msgclass
     CandidateNodeEntry = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("antd.v1.CandidateNodeEntry").msgclass
     FinalizeUploadRequest = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("antd.v1.FinalizeUploadRequest").msgclass

data/lib/antd/v1/upload_services_pb.rb

@@ -40,8 +40,10 @@ module Antd
         rpc :PrepareDataUpload, ::Antd::V1::PrepareDataUploadRequest, ::Antd::V1::PrepareUploadResponse
         # Phase 2: finalize an upload after the external EVM payment has landed.
         # For wave-batch uploads pass `tx_hashes`; for merkle uploads pass
-        # `winner_pool_hash` from the `MerklePaymentMade` event. The server-side
-        # stored upload state is consumed (one-shot).
+        # `winner_pool_hashes` — one `MerklePaymentMade` winner hash per entry in
+        # the prepare response's `merkle_batches` (`winner_pool_hash` remains
+        # accepted when there is exactly one batch). The server-side stored upload
+        # state is consumed (one-shot) once inputs validate.
         rpc :FinalizeUpload, ::Antd::V1::FinalizeUploadRequest, ::Antd::V1::FinalizeUploadResponse
       end
 

data/lib/antd/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Antd
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: antd
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - WithAutonomi
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-15 00:00:00.000000000 Z
+date: 2026-09-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: grpc