antd 0.1.0 → 0.3.0

data/lib/antd/grpc_manifests.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require_relative "manifests"
+require_relative "grpc_client"
+require_relative "v1/manifests_services_pb"
+
+# The manifest methods on +Antd::GrpcClient+, over ManifestService. The
+# models and the entry check are in manifests.rb, shared with REST.
+module Antd
+  # Channel arguments for the manifest stub's own channel. grpc-ruby has no
+  # per-call message limit, so ManifestService gets a channel of its own
+  # with both limits raised to +MANIFEST_GRPC_MAX_MESSAGE+; the other
+  # services keep gRPC's defaults.
+  MANIFEST_GRPC_CHANNEL_ARGS = {
+    "grpc.max_receive_message_length" => MANIFEST_GRPC_MAX_MESSAGE,
+    "grpc.max_send_message_length" => MANIFEST_GRPC_MAX_MESSAGE
+  }.freeze
+
+  class GrpcClient
+    # --- Manifests ---
+    #
+    # The same methods and models as the REST +Client+ (see there). The
+    # `.ant` bytes travel raw over gRPC; REST's base64 never shows. Unset
+    # optionals (proto3 +optional+ without a value, or an empty string) read
+    # as nil, as REST's omitted fields do.
+
+    # Mirrors +Client#build_manifest+. Nothing is paid for.
+    #
+    # Needs antd 0.16.0 or later.
+    #
+    # @return [BuiltManifest]
+    # @raise [BadRequestError] an entry with both or neither of +data_map+ and
+    #   +address+, or a bad +size+, before anything is sent
+    # @raise [BadRequestError] an entry the daemon rejects (INVALID_ARGUMENT);
+    #   the message names +entries[i]+
+    def build_manifest(entries, name: nil, torrent_info_hashes: nil, embed_roots: true)
+      inputs = Antd.manifest_entry_inputs(entries)
+      req = Antd::V1::BuildManifestRequest.new(
+        torrent_info_hashes: Array(torrent_info_hashes),
+        # Always sent, so "unset means true" never depends on the daemon.
+        embed_roots: embed_roots ? true : false,
+        entries: inputs.map { |e| manifest_entry_input_pb(e) }
+      )
+      req.name = name unless name.nil? || name.empty?
+
+      resp = grpc_call { manifest_stub.build(req) }
+      BuiltManifest.new(
+        manifest: resp.manifest,
+        link: manifest_pb_string(resp.link),
+        entries: resp.entries.map { |e| manifest_entry_info_from_pb(e) }
+      )
+    end
+
+    # Mirrors +Client#decode_manifest+. The bytes are sent raw.
+    #
+    # Needs antd 0.16.0 or later.
+    #
+    # @return [DecodedManifest]
+    def decode_manifest(manifest, resolve: false)
+      raise BadRequestError, MANIFEST_DECODE_NEEDS_INPUT if manifest.nil? || manifest.empty?
+
+      decode_manifest_pb(Antd::V1::DecodeManifestRequest.new(manifest: manifest.b, resolve: resolve ? true : false))
+    end
+
+    # Mirrors +Client#decode_manifest_link+.
+    #
+    # Needs antd 0.16.0 or later.
+    #
+    # @return [DecodedManifest]
+    def decode_manifest_link(link, resolve: false)
+      raise BadRequestError, MANIFEST_DECODE_NEEDS_INPUT if link.nil? || link.empty?
+
+      decode_manifest_pb(Antd::V1::DecodeManifestRequest.new(link: link, resolve: resolve ? true : false))
+    end
+
+    private
+
+    # ManifestService on its own channel, with +MANIFEST_GRPC_CHANNEL_ARGS+.
+    # Made on first use, so +initialize+ stays as it is.
+    def manifest_stub
+      @manifest_stub ||= Antd::V1::ManifestService::Stub.new(
+        @target, :this_channel_is_insecure, channel_args: MANIFEST_GRPC_CHANNEL_ARGS
+      )
+    end
+
+    def decode_manifest_pb(req)
+      resp = grpc_call { manifest_stub.decode(req) }
+      DecodedManifest.new(
+        source: resp.source,
+        name: resp.has_name? ? manifest_pb_string(resp.name) : nil,
+        torrent_info_hash_v1: manifest_pb_string(resp.torrent_info_hash_v1),
+        torrent_info_hash_v2: manifest_pb_string(resp.torrent_info_hash_v2),
+        entries: resp.entries.map { |e| manifest_entry_info_from_pb(e) }
+      )
+    end
+
+    def manifest_entry_input_pb(e)
+      attrs = {}
+      attrs[:path] = e.path unless e.path.nil? || e.path.empty?
+      attrs[:size] = e.size unless e.size.nil?
+      if e.data_map.nil? || e.data_map.empty?
+        attrs[:address] = e.address
+      else
+        attrs[:data_map] = e.data_map
+      end
+      Antd::V1::ManifestEntryInput.new(**attrs)
+    end
+
+    # proto3 +optional+ sizes are checked for presence: unset is nil, not 0.
+    def manifest_entry_info_from_pb(e)
+      ManifestEntryInfo.new(
+        effective_name: e.effective_name,
+        path: e.has_path? ? manifest_pb_string(e.path) : nil,
+        size: e.has_size? ? e.size : nil,
+        kind: e.kind,
+        content_address: e.content_address,
+        data_map: manifest_pb_string(e.data_map),
+        exact_size: e.has_exact_size? ? e.exact_size : nil,
+        error: manifest_pb_string(e.error)
+      )
+    end
+
+    # A proto string, or nil when empty.
+    def manifest_pb_string(value)
+      value.nil? || value.empty? ? nil : value
+    end
+  end
+end

data/lib/antd/manifests.rb

@@ -0,0 +1,300 @@
+# frozen_string_literal: true
+
+require "base64"
+require_relative "models"
+require_relative "errors"
+require_relative "client"
+
+# Manifests (ADR-0006): `.ant` files and `ant://` links that describe a set
+# of files, each with an optional path and size and either an embedded
+# DataMap or a public DataMap address. The daemon builds and decodes them
+# through ant-core, so callers never re-implement the format. Nothing is
+# uploaded or paid for.
+#
+# This file holds the models and the REST methods on +Antd::Client+;
+# grpc_manifests.rb adds the same methods to +Antd::GrpcClient+.
+module Antd
+  # +ManifestEntryInfo#kind+ values.
+  module ManifestEntryKind
+    # The manifest carries the entry's DataMap: it is the key to the file.
+    EMBEDDED = "embedded"
+    # The manifest carries a public file's DataMap address.
+    PUBLIC   = "public"
+  end
+
+  # +DecodedManifest#source+ values.
+  module ManifestSource
+    # `.ant` bytes or an `ant://manifest/` link.
+    MANIFEST  = "manifest"
+    # A file link or bare address, reported as one public entry with no path.
+    FILE_LINK = "file_link"
+  end
+
+  # One file for +build_manifest+. Set exactly one of +data_map+ or
+  # +address+; a Hash with the same keys works too.
+  #
+  # - +path+: the relative path the entry extracts under, subject to the
+  #   portable path rules. nil: it extracts under its content address.
+  # - +size+: the plaintext size to record, as given (the creator's claim).
+  #   nil: none is recorded; readers take the exact size from an embedded
+  #   root DataMap.
+  # - +data_map+: a hex DataMap, as the upload methods return it. The entry
+  #   embeds it.
+  # - +address+: a public file's DataMap address (hex, 32 bytes).
+  ManifestEntryInput = Struct.new(:path, :size, :data_map, :address, keyword_init: true) do
+    def initialize(path: nil, size: nil, data_map: nil, address: nil)
+      super
+    end
+  end
+
+  # What a manifest says about one entry. Unset fields are nil on both
+  # transports (REST omits them; gRPC sends no value or an empty string),
+  # so a +size+ or +exact_size+ the manifest lacks is nil, never 0.
+  #
+  # - +effective_name+: +path+, or the content address in hex when there is
+  #   none.
+  # - +path+: the entry's path, or nil.
+  # - +size+: the size recorded in the manifest (the creator's claim), or nil.
+  # - +kind+: a +ManifestEntryKind+ string.
+  # - +content_address+: hex. The file's public DataMap address, whether or
+  #   not it was ever made public; the same for private and public uploads
+  #   of one file.
+  # - +data_map+: the embedded DataMap in the hex form the download methods
+  #   accept. Decode only; nil for public entries.
+  # - +exact_size+: the exact plaintext size, from an embedded root DataMap
+  #   or after a resolving decode; nil when unknown.
+  # - +error+: why a resolving decode failed for this entry, or nil. A
+  #   failed entry does not fail the call.
+  ManifestEntryInfo = Struct.new(
+    :effective_name, :path, :size, :kind, :content_address, :data_map, :exact_size, :error,
+    keyword_init: true
+  ) do
+    def initialize(effective_name: "", path: nil, size: nil, kind: "", content_address: "",
+                   data_map: nil, exact_size: nil, error: nil)
+      super
+    end
+  end
+
+  # Result of +build_manifest+.
+  #
+  # - +manifest+: the `.ant` bytes (a binary String).
+  # - +link+: the `ant://manifest/` link, or nil when it would not fit the
+  #   recommended 1,500 bytes.
+  # - +entries+: +ManifestEntryInfo+s in encoded order (sorted by effective
+  #   name).
+  BuiltManifest = Struct.new(:manifest, :link, :entries, keyword_init: true)
+
+  # Result of +decode_manifest+ and +decode_manifest_link+.
+  #
+  # - +source+: a +ManifestSource+ string.
+  # - +name+: the suggested root directory name, or nil.
+  # - +torrent_info_hash_v1+, +torrent_info_hash_v2+: hex, or nil when absent.
+  # - +entries+: +ManifestEntryInfo+s.
+  DecodedManifest = Struct.new(
+    :source, :name, :torrent_info_hash_v1, :torrent_info_hash_v2, :entries,
+    keyword_init: true
+  )
+
+  # The gRPC message ceiling for manifest calls, both ways: a manifest can be
+  # 64 MiB, and a decode response carries its DataMaps in hex. gRPC's default
+  # receive limit is 4 MiB.
+  MANIFEST_GRPC_MAX_MESSAGE = 256 * 1024 * 1024
+
+  # The daemon's cap on the entry errors one 400 names.
+  MANIFEST_MAX_REPORTED_ENTRY_ERRORS = 20
+  private_constant :MANIFEST_MAX_REPORTED_ENTRY_ERRORS
+
+  # The daemon's message for empty decode input (empty bytes or link).
+  MANIFEST_DECODE_NEEDS_INPUT = "needs a manifest (base64 .ant bytes) or a link"
+
+  # Normalises +build_manifest+ entries to +ManifestEntryInput+s before
+  # anything is sent. A refusal is the +BadRequestError+ (400) the daemon
+  # would send, with its wording: every bad entry (both or neither of
+  # +data_map+ and +address+, nil and "" counting as unset; or a +size+ that
+  # is not a non-negative Integer) is collected and named as
+  # "N invalid entries: entries[i]: ...; entries[j]: ..." (at most 20, then
+  # "; and K more").
+  #
+  # @api private
+  # @param entries [Array<ManifestEntryInput, Hash>]
+  # @return [Array<ManifestEntryInput>]
+  # @raise [BadRequestError]
+  def self.manifest_entry_inputs(entries)
+    raise BadRequestError, "entries must be an Array" unless entries.is_a?(Array)
+
+    errors = []
+    inputs = entries.each_with_index.map do |e, i|
+      e = ManifestEntryInput.new(**e.transform_keys(&:to_sym)) if e.is_a?(Hash)
+      unless e.is_a?(ManifestEntryInput)
+        errors << "entries[#{i}]: must be a ManifestEntryInput or Hash"
+        next
+      end
+
+      has_data_map = !(e.data_map.nil? || e.data_map.empty?)
+      has_address = !(e.address.nil? || e.address.empty?)
+      if has_data_map && has_address
+        errors << "entries[#{i}]: give data_map or address, not both"
+      elsif !has_data_map && !has_address
+        errors << "entries[#{i}]: needs a data_map or an address"
+      end
+      unless e.size.nil? || (e.size.is_a?(Integer) && e.size >= 0)
+        errors << "entries[#{i}]: size must be a non-negative Integer or nil"
+      end
+      e
+    rescue ArgumentError
+      # A Hash with a key ManifestEntryInput does not have.
+      errors << "entries[#{i}]: unknown field (expected path, size, data_map, address)"
+      nil
+    end
+    raise BadRequestError, Antd.manifest_entry_errors_message(errors) unless errors.empty?
+
+    inputs
+  end
+
+  # The daemon's +entry_errors_message+.
+  #
+  # @api private
+  def self.manifest_entry_errors_message(errors)
+    shown = errors.first(MANIFEST_MAX_REPORTED_ENTRY_ERRORS).join("; ")
+    message = "#{errors.length} invalid entries: #{shown}"
+    message += "; and #{errors.length - MANIFEST_MAX_REPORTED_ENTRY_ERRORS} more" if errors.length > MANIFEST_MAX_REPORTED_ENTRY_ERRORS
+    message
+  end
+
+  class Client
+    # --- Manifests ---
+
+    # Build a `.ant` manifest from DataMaps and public addresses already in
+    # hand (POST /v1/manifests/build). Nothing is uploaded or paid for.
+    #
+    # By default the daemon resolves each shrunk DataMap's root (fetching its
+    # wrapper records) and embeds it when it is at most 64 KiB, so recipients
+    # skip that fetch (ADR-0006's policy). That reads from the network, so the
+    # call can time out; it is safe to retry.
+    #
+    # Needs antd 0.16.0 or later.
+    #
+    # @param entries [Array<ManifestEntryInput, Hash>] each with exactly one
+    #   of +data_map+ or +address+; checked before anything is sent
+    # @param name [String, nil] suggested root directory name (one portable
+    #   path component)
+    # @param torrent_info_hashes [Array<String>, nil] BitTorrent info hashes
+    #   of the same files: hex, 40 characters for v1 and/or 64 for v2
+    # @param embed_roots [Boolean] false embeds shrunk DataMaps exactly as
+    #   given (the wire's +embed_roots+; default true)
+    # @return [BuiltManifest]
+    # @raise [BadRequestError] an entry with both or neither of +data_map+ and
+    #   +address+, or a bad +size+, worded as the daemon words it
+    # @raise [BadRequestError] an entry the daemon rejects; the message names
+    #   +entries[i]+
+    def build_manifest(entries, name: nil, torrent_info_hashes: nil, embed_roots: true)
+      inputs = Antd.manifest_entry_inputs(entries)
+      wire = inputs.map do |e|
+        m = {}
+        m[:path] = e.path unless e.path.nil? || e.path.empty?
+        m[:size] = e.size unless e.size.nil?
+        if e.data_map.nil? || e.data_map.empty?
+          m[:address] = e.address
+        else
+          m[:data_map] = e.data_map
+        end
+        m
+      end
+      body = { entries: wire, embed_roots: embed_roots ? true : false }
+      body[:name] = name unless name.nil? || name.empty?
+      hashes = Array(torrent_info_hashes)
+      body[:torrent_info_hashes] = hashes unless hashes.empty?
+
+      j = do_json(:post, "/v1/manifests/build", body)
+      BuiltManifest.new(
+        manifest: manifest_bytes_from_b64(j["manifest"]),
+        link: manifest_string(j["link"]),
+        entries: manifest_entry_infos(j["entries"])
+      )
+    end
+
+    # Decode `.ant` bytes (POST /v1/manifests/decode). With +resolve+, the
+    # daemon fetches each entry's DataMap (and wrapper records) to report
+    # +exact_size+ and confirm the DataMap is on the network; content chunks
+    # are not fetched, and one entry's failure is reported in its +error+,
+    # not as a failed call. Nothing is paid for; safe to retry.
+    #
+    # Needs antd 0.16.0 or later.
+    #
+    # @param manifest [String] the `.ant` bytes
+    # @param resolve [Boolean]
+    # @return [DecodedManifest]
+    # @raise [BadRequestError] an empty +manifest+
+    # @raise [BadRequestError] bytes that are not a manifest
+    def decode_manifest(manifest, resolve: false)
+      raise BadRequestError, MANIFEST_DECODE_NEEDS_INPUT if manifest.nil? || manifest.empty?
+
+      post_manifest_decode({ manifest: b64_encode(manifest), resolve: resolve ? true : false })
+    end
+
+    # Decode an `ant://` manifest link, file link or bare 64-hex address
+    # (POST /v1/manifests/decode). See +decode_manifest+ for +resolve+.
+    #
+    # Needs antd 0.16.0 or later.
+    #
+    # @param link [String]
+    # @param resolve [Boolean]
+    # @return [DecodedManifest]
+    # @raise [BadRequestError] an empty +link+
+    # @raise [BadRequestError] a link the daemon cannot read
+    def decode_manifest_link(link, resolve: false)
+      raise BadRequestError, MANIFEST_DECODE_NEEDS_INPUT if link.nil? || link.empty?
+
+      post_manifest_decode({ link: link, resolve: resolve ? true : false })
+    end
+
+    private
+
+    def post_manifest_decode(body)
+      j = do_json(:post, "/v1/manifests/decode", body)
+      DecodedManifest.new(
+        source: j["source"] || "",
+        name: manifest_string(j["name"]),
+        torrent_info_hash_v1: manifest_string(j["torrent_info_hash_v1"]),
+        torrent_info_hash_v2: manifest_string(j["torrent_info_hash_v2"]),
+        entries: manifest_entry_infos(j["entries"])
+      )
+    end
+
+    # The build response's base64 `.ant` bytes, raw.
+    def manifest_bytes_from_b64(value)
+      b64_decode(value.to_s)
+    rescue ArgumentError => e
+      raise InternalError, "build_manifest: manifest is not valid base64: #{e.message}"
+    end
+
+    def manifest_entry_infos(raw)
+      return [] unless raw.is_a?(Array)
+
+      raw.filter_map do |e|
+        next unless e.is_a?(Hash)
+
+        ManifestEntryInfo.new(
+          effective_name: e["effective_name"] || "",
+          path: manifest_string(e["path"]),
+          size: manifest_size(e["size"]),
+          kind: e["kind"] || "",
+          content_address: e["content_address"] || "",
+          data_map: manifest_string(e["data_map"]),
+          exact_size: manifest_size(e["exact_size"]),
+          error: manifest_string(e["error"])
+        )
+      end
+    end
+
+    # An optional size: a JSON integer, or nil when absent (never 0).
+    def manifest_size(value)
+      value.is_a?(Integer) && value >= 0 ? value : nil
+    end
+
+    # An optional string: nil when absent or empty.
+    def manifest_string(value)
+      value.is_a?(String) && !value.empty? ? value : nil
+    end
+  end
+end

data/lib/antd/models.rb

@@ -195,4 +195,225 @@ module Antd
     end
     alias_method :is_meta, :meta?
   end
+
+  # One +payments+ quote in full signed form, returned by +pointer_prepare+
+  # when called with +include_signed_quotes: true+. +quote+ and
+  # +commitment_sidecar+ are opaque base64 strings on both transports (the
+  # gRPC client encodes the proto's bytes the same way); only antd parses
+  # them. +commitment_sidecar+ is nil for baseline quotes.
+  SignedQuoteEntry = Struct.new(:quote_hash, :quote, :commitment_sidecar, keyword_init: true)
+
+  # --- Pointers (ADR-0016 / ADR-0018 in ant-node) ---
+  #
+  # 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. antd signs with owner keys it loaded at startup
+  # (+--pointer-keys+), so a write names the pointer by its address (+owner+),
+  # never by a key.
+  #
+  # Every write pays, and every attempt pays again: never retry a create,
+  # update, transfer or finalize automatically.
+
+  # Counter of a pointer's final state, after a transfer or a freeze:
+  # 2^64 - 1 (u64::MAX). Nothing can replace a state at this counter.
+  POINTER_FINAL_COUNTER = 18_446_744_073_709_551_615
+
+  # What a pointer's target is. Pass as +kind:+ to the pointer writes; the
+  # daemon defaults to +CHUNK+ when it is omitted.
+  module PointerKind
+    # An immutable chunk, such as a public file's data map. The default.
+    CHUNK = "chunk"
+    # Another pointer: a forwarding the owner can still change. Use
+    # +pointer_transfer+ to hand a pointer over for good.
+    POINTER = "pointer"
+
+    # The kind a raw +kind_tag+ names (0 chunk, 1 pointer), or nil for a tag
+    # this SDK does not know.
+    #
+    # @param tag [Integer]
+    # @return [String, nil]
+    def self.from_tag(tag)
+      case tag
+      when 0 then CHUNK
+      when 1 then POINTER
+      end
+    end
+  end
+
+  # The write +pointer_prepare+ signs for an external signer.
+  module PointerOp
+    # Create the pointer at +target+. Refused if it already exists.
+    CREATE = "create"
+    # Point the pointer at +target+, creating it if it does not exist.
+    UPDATE = "update"
+    # Hand the pointer over for good to the pointer at +recipient+, which must
+    # already exist. Irreversible once stored.
+    TRANSFER = "transfer"
+  end
+
+  # Where a pointer stands with respect to finality (+PointerFinality#status+).
+  #
+  # The status is the daemon's wire string. These are the values this SDK
+  # knows; a newer daemon may send another, which is kept verbatim (the
+  # "unknown" arm: +PointerFinality#status_known?+ is false). Give a +case+
+  # over the status an +else+ branch.
+  module PointerFinalityStatus
+    # No peer that answered holds a final state: the owner can still move the
+    # pointer. Rules a final state out only when every peer answered.
+    OPEN = "open"
+    # One final state, not yet held by a majority: a transfer still
+    # spreading, or a write that fell short.
+    SETTLING = "settling"
+    # One final state held by a majority, but not every peer answered, so a
+    # rival could still be unseen. Ask again.
+    UNCONFIRMED = "unconfirmed"
+    # One final state held by a majority, every peer answered, no rival. The
+    # only status a recipient should rely on.
+    FINAL = "final"
+    # The owner signed two or more different final states.
+    FORKED = "forked"
+
+    # Every status this SDK knows.
+    KNOWN = [OPEN, SETTLING, UNCONFIRMED, FINAL, FORKED].freeze
+
+    # @param status [String]
+    # @return [Boolean] whether this SDK knows +status+
+    def self.known?(status)
+      KNOWN.include?(status)
+    end
+  end
+
+  # The state a pointer write stored (+pointer_create+ / +pointer_update+).
+  # +counter+ is an Integer; a final state sits at +POINTER_FINAL_COUNTER+.
+  PointerWriteResult = Struct.new(:address, :state_id, :counter, keyword_init: true)
+
+  # A pointer's current state, as the network serves it (+pointer_get+).
+  #
+  # - +owner+: the owner's ML-DSA-65 public key (hex, 1,952 bytes). The
+  #   address is derived from it, so it is the proof of who owns the pointer.
+  # - +counter+: Integer, +POINTER_FINAL_COUNTER+ once final.
+  # - +kind+: "chunk", "pointer", or "unknown" for a kind the daemon does not
+  #   know; +kind_tag+ carries the raw value either way.
+  # - +is_final+: the state is at the final counter, so nothing can replace it.
+  # - +transferred_to+: the pointer this one was handed over to, or nil.
+  PointerRecord = Struct.new(
+    :address, :owner, :counter, :kind, :kind_tag, :target, :state_id,
+    :is_final, :transferred_to,
+    keyword_init: true
+  ) do
+    # @return [Boolean] true at the final counter: transferred or frozen
+    def final?
+      is_final == true
+    end
+
+    # @return [String, nil] the target's +PointerKind+, if this SDK knows its tag
+    def target_kind
+      PointerKind.from_tag(kind_tag)
+    end
+  end
+
+  # Where a chain of pointers ends (+pointer_resolve+): the target's +kind+
+  # ("chunk", or "unknown" for a kind the daemon does not know), its raw
+  # +kind_tag+ and the +target+ address.
+  PointerTarget = Struct.new(:kind, :kind_tag, :target, keyword_init: true) do
+    # @return [String, nil] the target's +PointerKind+, if this SDK knows its tag
+    def target_kind
+      PointerKind.from_tag(kind_tag)
+    end
+  end
+
+  # One final state, as a finality check reports it. +holders+ is how many
+  # peers of the close group hold it; +transferred_to+ is nil unless the
+  # state is a transfer.
+  PointerFinalState = Struct.new(
+    :state_id, :kind, :kind_tag, :target, :holders, :transferred_to,
+    keyword_init: true
+  )
+
+  # Where a pointer stands, as its whole close group reports it
+  # (+pointer_finality+). Check it before relying on a transfer: only
+  # +final?+ means the transfer is beyond dispute.
+  #
+  # - +group+ / +answered+: peers in the close group, and peers that answered.
+  # - +status+: a +PointerFinalityStatus+ string (see there for unknown ones).
+  # - +counter+: +open+ only, the Integer counter a read would return, or nil
+  #   when no state is corroborated.
+  # - +state+: +settling+, +unconfirmed+ and +final+, the one final state seen
+  #   (+PointerFinalState+), else nil.
+  # - +states+ / +majority+: +forked+ only, every final state seen (most-held
+  #   first) and the one a majority holds, which reads return. +states+ is
+  #   empty and +majority+ nil otherwise.
+  # - +transferred_to+: the pointer this one was handed over to, once that is
+  #   beyond dispute (status +final+), else nil.
+  PointerFinality = Struct.new(
+    :address, :group, :answered, :status, :counter, :state, :states,
+    :majority, :transferred_to,
+    keyword_init: true
+  ) do
+    # @return [Boolean] one final state, held by a majority, every peer
+    #   answering and no rival seen
+    def final?
+      status == PointerFinalityStatus::FINAL
+    end
+
+    # @return [Boolean] false for a status a newer daemon added
+    def status_known?
+      PointerFinalityStatus.known?(status)
+    end
+  end
+
+  # Whose pointer decides what an address resolves to, after following every
+  # transfer (+pointer_controller+). +transfers+ lists every pointer the
+  # address was handed over to, in order; +frozen+ is true when +pointer+ is
+  # final without being handed over, so nobody can move it.
+  PointerController = Struct.new(:pointer, :transfers, :frozen, keyword_init: true)
+
+  # What a transfer stored, and where the close group says it stands.
+  # +finality+ (a +PointerFinality+) is nil when that check failed, and
+  # +finality_error+ says why; the transfer itself is stored and final either
+  # way. Ask again with +pointer_finality+.
+  PointerTransferResult = Struct.new(:address, :state_id, :finality, :finality_error, keyword_init: true)
+
+  # A pointer write signed by the daemon and quoted for an external signer
+  # (+pointer_prepare+). Pay +payments+ with +payForQuotes()+, then call
+  # +pointer_finalize+. +op+ is a +PointerOp+ string, +counter+ an Integer,
+  # +payment_type+ always "wave_batch" (a pointer state is paid with one
+  # quote). +signed_quotes+ (+SignedQuoteEntry+) is filled only when the
+  # prepare asked for it, else empty.
+  #
+  # While it awaits payment, other writes to the pointer raise
+  # +ConflictError+ until it is finalized or expires (one hour).
+  PointerPrepareResult = Struct.new(
+    :upload_id, :op, :address, :state_id, :counter, :payment_type,
+    :payments, :total_amount, :payment_vault_address, :payment_token_address,
+    :rpc_url, :signed_quotes,
+    keyword_init: true
+  )
+
+  # The state a pointer finalize stored. +finality+ is set for a transfer
+  # (where the close group says it stands), else nil.
+  PointerFinalizeResult = Struct.new(:address, :state_id, :counter, :finality, keyword_init: true)
+
+  # Parses a pointer counter. The daemon sends counters as decimal strings on
+  # both transports, because a final state sits at 2^64 - 1, past what a JSON
+  # number keeps exactly in many languages. Ruby integers are unbounded, so
+  # the value is checked against the daemon's u64 range here.
+  #
+  # Strict: only a String of ASCII digits within u64 parses. +Integer()+ alone
+  # would also take a sign, underscores or a radix prefix, and a malformed
+  # counter must never read as 0.
+  #
+  # @param field [String] the field name, for the error message
+  # @param value [Object] the wire value
+  # @return [Integer]
+  # @raise [InternalError] when +value+ is not a decimal u64
+  def self.parse_pointer_counter(field, value)
+    if value.is_a?(String) && value.match?(/\A[0-9]+\z/)
+      n = Integer(value, 10)
+      return n if n <= POINTER_FINAL_COUNTER
+    end
+    raise InternalError, "invalid pointer #{field} #{value.inspect}: expected a decimal u64"
+  end
 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