opentimestamps 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6f146094f21ed3a732a3a7cfa6b799366a25a2434953d16dcf3825052f3c967a
+  data.tar.gz: '08b95d3c6e8e7b3853e4753d76171e72eb46b9645c07454ebf6ea2b1407510db'
+SHA512:
+  metadata.gz: 1d063990950ea15459b67adf25fdb8699dec5ff1ce75901cefdeee5c03b34373207b6a7ec988c1764cc19458576254cc0b8a06e796ea9ad98d282776c63d34c5
+  data.tar.gz: 41756a3dd2934d2f236b43c5738524cf121a62f692c026144910aa8150525cad8aa2891585e1bb58ba62ea6b5a39f40c617c7d8d617b31dc98d02208b02bfe1e

data/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+The format follows [Keep a Changelog](https://keepachangelog.com/), and this
+project uses [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0]
+
+Initial release: a pure-Ruby OpenTimestamps client with no runtime dependencies.
+
+### Added
+
+- `OpenTimestamps.stamp` and `.stamp_digest` submit a hash to the calendar
+  servers (`stamp_digest` keeps the content itself private) and merge the
+  replies, so one calendar being down is not fatal.
+- `OpenTimestamps.upgrade` folds a calendar's Bitcoin path into a pending proof;
+  `verify` / `verified?` check it against a block through a `Chain` oracle and
+  fail closed.
+- `DetachedTimestampFile` reads and writes the `.ots` file format.
+- `Timestamp`, `Op`, and `Attestation` (Pending, Bitcoin, Unknown) model the wire
+  format, with byte-exact serialization and unknown attestation types preserved
+  intact.
+- `Keccak256`, a pure-Ruby implementation of Ethereum's Keccak-256, for proofs
+  that also anchor to Ethereum.
+- `Chain::Explorer`, a public block-explorer oracle behind a small interface a
+  Bitcoin node can replace.
+
+The parser is hardened against untrusted input (depth, varuint, and message-size
+caps; only `DeserializationError` on malformed bytes). Tested with byte-exact
+round-trips of twelve reference vectors, an offline check against Bitcoin block
+358391, and Keccak-256 known-answer vectors.
+
+[Unreleased]: https://github.com/sirruf/opentimestamps/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/sirruf/opentimestamps/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Artem Kolesnikov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,88 @@
+# opentimestamps
+
+A pure-Ruby client for [OpenTimestamps](https://opentimestamps.org), with no
+runtime dependencies. It stamps a hash against the Bitcoin blockchain through
+public calendar servers, upgrades the resulting proof to a block attestation,
+and verifies it, using only the standard library (`digest`, `openssl`,
+`net/http`, `json`). The proofs it produces are self-verifying and stay valid
+without this gem or any particular server.
+
+The reference OpenTimestamps clients are Python and JavaScript; nothing
+equivalent is published for Ruby on RubyGems. This gem lets a Ruby app anchor
+and verify timestamps in-process, without shelling out to another language.
+
+## Install
+
+```ruby
+gem "opentimestamps"
+```
+
+## Usage
+
+```ruby
+require "opentimestamps"
+
+# Stamp: hashes the data (SHA-256), submits the digest to the default calendars,
+# and returns a pending proof. Use stamp_digest to submit a precomputed hash and
+# keep the content itself private.
+ots = OpenTimestamps.stamp("hello world\n")
+
+# Persist it. The calendar indexes each submission by a per-request commitment,
+# so if you keep only the hash you can never upgrade. Always save the .ots.
+File.binwrite("hello.txt.ots", ots.serialize)
+
+# Upgrade, an hour or so later, once a calendar has anchored the commitment in a
+# Bitcoin transaction. Returns true if the file changed.
+ots = OpenTimestamps::DetachedTimestampFile.deserialize(File.binread("hello.txt.ots"))
+OpenTimestamps.upgrade(ots) && File.binwrite("hello.txt.ots", ots.serialize)
+
+# Verify against the chain. Raises VerificationError unless a block attestation
+# matches; returns the confirmed attestations, each carrying the proven digest.
+OpenTimestamps.verify(ots)
+# => [#<struct Verification height=358391, time=2015-05-28 ..., digest="\x00..">]
+
+OpenTimestamps.verified?(ots)   # boolean form; never raises
+```
+
+Compare `verify`'s `digest` against the hash of your own file to bind the proof
+to your document.
+
+## Notes on the design
+
+The parser treats its input as untrusted: malformed bytes, oversized length
+prefixes, and pathologically deep or large proofs all raise `DeserializationError`
+rather than a raw Ruby error, and depth and message-size caps bound the work a
+single proof can cause.
+
+Verification goes through a `Chain` oracle (`#block_merkle_root_and_time`), so
+the bundled public-explorer adapter can be swapped for your own Bitcoin node when
+you want a check that trusts nothing external.
+
+Attestation types the library does not model (Litecoin, Ethereum, or anything
+added later) are carried through untouched, so re-serializing a proof never
+corrupts it. Ethereum's Keccak-256 is implemented in pure Ruby for the proofs
+that need it; Bitcoin proofs never do.
+
+The client never broadcasts a Bitcoin transaction. Calendars batch many digests
+into one; the client only submits and upgrades.
+
+## Interop
+
+`test/vectors/` holds twelve `.ots` files produced by the reference client
+(among them the timestamp of the Bitcoin whitepaper, plus multi-chain, unknown
+notary, and merkle-tree proofs). The suite asserts each one re-serializes
+byte-for-byte, and checks a proof against Bitcoin block 358391 using a recorded
+merkle root, offline. The reference `ots` client also reads proofs this gem
+creates.
+
+## Roadmap
+
+- [x] Byte-exact interop with reference `.ots` vectors, both directions.
+- [x] Multi-calendar submit with merge (a single calendar being down is not fatal).
+- [ ] `Chain::BitcoinCore` JSON-RPC adapter (verification against your own node).
+- [ ] Calendar quorum on upgrade (m-of-n).
+- [ ] Optional CLI (`ots stamp | upgrade | verify | info`).
+
+## License
+
+MIT.

data/lib/opentimestamps/attestation.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module OpenTimestamps
+  # A leaf claim about a commitment: a pending calendar promise, a Bitcoin block
+  # header, or an unknown type kept verbatim for forward compatibility.
+  module Attestation
+    PENDING_TAG = "\x83\xDF\xE3\x0D\x2E\xF9\x0C\x8E".b
+    BITCOIN_TAG = "\x05\x88\x96\x0D\x73\xD7\x19\x01".b
+
+    # Layout: an 8-byte tag then a length-prefixed payload. The length prefix
+    # means an unknown tag can be preserved whole. For a known tag we require
+    # the payload to be fully consumed, so a crafted trailing byte is rejected
+    # rather than silently dropped.
+    def self.deserialize(reader)
+      tag = reader.read(8)
+      payload = reader.varbytes
+      return Unknown.new(tag, payload) unless [PENDING_TAG, BITCOIN_TAG].include?(tag)
+
+      inner = Serialization::Reader.new(payload)
+      att = tag == PENDING_TAG ? Pending.new(inner.varbytes) : Bitcoin.new(inner.varuint)
+      raise DeserializationError, "trailing bytes in attestation payload" unless inner.eof?
+
+      att
+    end
+
+    # Value equality across attestation types, keyed on each type's components.
+    class Base
+      def bitcoin? = false
+      def pending? = false
+
+      def ==(other)
+        other.class == self.class && other.components == components
+      end
+      alias eql? ==
+
+      def hash = [self.class, *components].hash
+    end
+
+    # A calendar has accepted the commitment; it is not yet in a block.
+    class Pending < Base
+      attr_reader :uri
+
+      def initialize(uri)
+        @uri = uri.dup.force_encoding("UTF-8")
+      end
+
+      def pending? = true
+      def components = [@uri]
+      def to_s = "PENDING #{@uri}"
+
+      def serialize(writer)
+        inner = Serialization::Writer.new.varbytes(@uri.b)
+        writer.write(PENDING_TAG).varbytes(inner.string)
+      end
+    end
+
+    # The commitment equals the merkle root of Bitcoin block +height+.
+    class Bitcoin < Base
+      attr_reader :height
+
+      def initialize(height)
+        @height = height
+      end
+
+      def bitcoin? = true
+      def components = [@height]
+      def to_s = "BITCOIN block ##{@height}"
+
+      def serialize(writer)
+        inner = Serialization::Writer.new.varuint(@height)
+        writer.write(BITCOIN_TAG).varbytes(inner.string)
+      end
+    end
+
+    # A type this version does not model (Litecoin, Ethereum, or something newer)
+    # carried through untouched so a round-trip never corrupts the proof.
+    class Unknown < Base
+      attr_reader :tag, :payload
+
+      def initialize(tag, payload)
+        @tag = tag.b
+        @payload = payload.b
+      end
+
+      def components = [@tag, @payload]
+      def to_s = "UNKNOWN(#{@tag.unpack1('H*')})"
+
+      def serialize(writer)
+        writer.write(@tag).varbytes(@payload)
+      end
+    end
+  end
+end

data/lib/opentimestamps/calendar.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+
+module OpenTimestamps
+  # HTTP client for an OpenTimestamps calendar server. The client never
+  # broadcasts a Bitcoin transaction itself; the calendar aggregates many
+  # digests into one transaction. We only submit and later upgrade.
+  class Calendar
+    MIME = "application/vnd.opentimestamps.v1"
+    MAX_RESPONSE_BYTES = 1 << 20 # a calendar reply is a small commitment path
+
+    attr_reader :url
+
+    def initialize(url)
+      @url = url.to_s.chomp("/")
+    end
+
+    # Submit a digest; returns a pending Timestamp rooted at that digest.
+    def submit(digest, timeout: 20)
+      req = Net::HTTP::Post.new(URI("#{@url}/digest"))
+      req["Content-Type"] = MIME
+      req.body = digest.b
+      code, body = request(req, timeout)
+      raise NetworkError, "calendar #{host}: HTTP #{code}" unless code == "200"
+
+      Timestamp.deserialize(Serialization::Reader.new(body), digest.b)
+    end
+
+    # Ask the calendar to upgrade a commitment to its Bitcoin path. Returns a
+    # Timestamp rooted at +commitment+, or nil if it is not anchored yet (404).
+    def upgrade(commitment, timeout: 20)
+      req = Net::HTTP::Get.new(URI("#{@url}/timestamp/#{commitment.unpack1('H*')}"))
+      code, body = request(req, timeout)
+      return nil if code == "404"
+      raise NetworkError, "calendar #{host}: HTTP #{code}" unless code == "200"
+
+      Timestamp.deserialize(Serialization::Reader.new(body), commitment.b)
+    end
+
+    private
+
+    def host = URI(@url).host
+
+    def request(req, timeout)
+      uri = URI(@url)
+      req["Accept"] = MIME
+      req["User-Agent"] = "opentimestamps-ruby/#{VERSION}"
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == "https")
+      http.open_timeout = timeout
+      http.read_timeout = timeout
+
+      http.start do |conn|
+        conn.request(req) do |res|
+          return [res.code, read_capped(res)]
+        end
+      end
+    rescue SocketError, SystemCallError, Net::OpenTimeout, Net::ReadTimeout,
+           OpenSSL::SSL::SSLError, IOError => e
+      raise NetworkError, "calendar #{host}: #{e.class}: #{e.message}"
+    end
+
+    def read_capped(res)
+      buffer = +"".b
+      res.read_body do |chunk|
+        buffer << chunk
+        raise NetworkError, "calendar #{host}: response exceeds #{MAX_RESPONSE_BYTES} bytes" if buffer.bytesize > MAX_RESPONSE_BYTES
+      end
+      buffer
+    end
+  end
+end

data/lib/opentimestamps/chain.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require "time"
+
+module OpenTimestamps
+  # A chain oracle resolves a block height to its merkle root (in internal byte
+  # order, matching what OTS operations produce) and its time. Verification
+  # depends only on this interface, so a Bitcoin node can be dropped in for a
+  # fully trustless check.
+  module Chain
+    # Public block explorer (Esplora API). Convenient, but trusts the explorer.
+    class Explorer
+      MAX_RESPONSE_BYTES = 1 << 20
+
+      def initialize(base = "https://blockstream.info/api", timeout: 20)
+        @base = base.chomp("/")
+        @timeout = timeout
+      end
+
+      def block_merkle_root_and_time(height)
+        hash = get("#{@base}/block-height/#{height}").strip
+        blk = JSON.parse(get("#{@base}/block/#{hash}"))
+        root_internal = [blk.fetch("merkle_root")].pack("H*").reverse # display -> internal
+        [root_internal, Time.at(blk.fetch("timestamp")).utc]
+      rescue JSON::ParserError, KeyError => e
+        raise NetworkError, "explorer returned unexpected data: #{e.class}"
+      end
+
+      private
+
+      def get(url)
+        uri = URI(url)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = (uri.scheme == "https")
+        http.open_timeout = @timeout
+        http.read_timeout = @timeout
+
+        http.start do |conn|
+          conn.request(Net::HTTP::Get.new(uri)) do |res|
+            raise NetworkError, "explorer: HTTP #{res.code}" unless res.code == "200"
+
+            return read_capped(res)
+          end
+        end
+      rescue SocketError, SystemCallError, Net::OpenTimeout, Net::ReadTimeout,
+             OpenSSL::SSL::SSLError, IOError => e
+        raise NetworkError, "explorer: #{e.class}: #{e.message}"
+      end
+
+      def read_capped(res)
+        buffer = +"".b
+        res.read_body do |chunk|
+          buffer << chunk
+          raise NetworkError, "explorer: response exceeds #{MAX_RESPONSE_BYTES} bytes" if buffer.bytesize > MAX_RESPONSE_BYTES
+        end
+        buffer
+      end
+    end
+  end
+end

data/lib/opentimestamps/detached_file.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module OpenTimestamps
+  # A `.ots` detached timestamp file: a magic header, a version, the operation
+  # used to hash the original file, and the timestamp of that file hash.
+  class DetachedTimestampFile
+    MAJOR_VERSION = 1
+    # file-hash op kind => digest length in bytes
+    HASH_OPS = { sha1: 20, ripemd160: 20, sha256: 32 }.freeze
+
+    attr_reader :file_hash_op, :timestamp
+
+    def initialize(file_hash_op, timestamp)
+      len = HASH_OPS[file_hash_op.kind]
+      raise Error, "#{file_hash_op.kind} is not a valid file-hash op" unless len
+      unless timestamp.msg.bytesize == len
+        raise Error, "digest must be #{len} bytes for #{file_hash_op.kind}, got #{timestamp.msg.bytesize}"
+      end
+
+      @file_hash_op = file_hash_op
+      @timestamp = timestamp
+    end
+
+    # Build a fresh, unstamped file from an already-computed digest.
+    def self.from_hash(digest, hash: :sha256)
+      new(Op.new(hash), Timestamp.new(digest))
+    end
+
+    def self.deserialize(bytes)
+      reader = Serialization::Reader.new(bytes)
+      magic = reader.read(Serialization::MAGIC.bytesize)
+      raise DeserializationError, "not an .ots file (bad magic)" unless magic == Serialization::MAGIC
+
+      major = reader.varuint
+      raise DeserializationError, "unsupported major version #{major}" unless major == MAJOR_VERSION
+
+      tag = reader.u8
+      kind = Op::UNARY[tag]
+      len = HASH_OPS[kind]
+      raise DeserializationError, format("unsupported file-hash op 0x%02x", tag) unless len
+
+      digest = reader.read(len)
+      file = new(Op.new(kind), Timestamp.deserialize(reader, digest))
+      raise DeserializationError, "trailing data after timestamp" unless reader.eof?
+
+      file
+    end
+
+    def serialize
+      w = Serialization::Writer.new
+      w.write(Serialization::MAGIC).varuint(MAJOR_VERSION)
+      w.u8(Op::TAG.fetch(@file_hash_op.kind))
+      w.write(@timestamp.msg)
+      @timestamp.serialize(w)
+      w.string
+    end
+
+    def file_digest = @timestamp.msg
+  end
+end

data/lib/opentimestamps/error.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module OpenTimestamps
+  # Base class for every error this library raises.
+  class Error < StandardError; end
+
+  # Raised when a byte stream does not parse as a valid OTS structure. All
+  # parsing of untrusted input funnels through this, never a raw Ruby error.
+  class DeserializationError < Error; end
+
+  # Raised when a proof does not verify against the chain (or has nothing to
+  # verify yet).
+  class VerificationError < Error; end
+
+  # Raised when a calendar or chain oracle cannot be reached or answers badly.
+  class NetworkError < Error; end
+end

data/lib/opentimestamps/keccak256.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module OpenTimestamps
+  # Ethereum's original Keccak-256 (0x01 padding), which OpenSSL does not ship
+  # and which differs from NIST SHA3-256 (0x06 padding). Reached only by OTS
+  # proofs that also anchor to Ethereum; Bitcoin proofs never use it.
+  module Keccak256
+    MASK = (1 << 64) - 1
+    RATE = 136 # bytes (1088-bit rate, 512-bit capacity -> 256-bit output)
+
+    RNDC = [0x0000000000000001, 0x0000000000008082, 0x800000000000808a, 0x8000000080008000,
+            0x000000000000808b, 0x0000000080000001, 0x8000000080008081, 0x8000000000008009,
+            0x000000000000008a, 0x0000000000000088, 0x0000000080008009, 0x000000008000000a,
+            0x000000008000808b, 0x800000000000008b, 0x8000000000008089, 0x8000000000008003,
+            0x8000000000008002, 0x8000000000000080, 0x000000000000800a, 0x800000008000000a,
+            0x8000000080008081, 0x8000000000008080, 0x0000000080000001, 0x8000000080008008].freeze
+    ROTC = [1, 3, 6, 10, 15, 21, 28, 36, 45, 55, 2, 14, 27, 41, 56, 8, 25, 43, 62, 18, 39, 61, 20, 44].freeze
+    PILN = [10, 7, 11, 17, 18, 3, 5, 16, 8, 21, 24, 4, 15, 23, 19, 13, 12, 2, 20, 14, 22, 9, 6, 1].freeze
+
+    module_function
+
+    def digest(message)
+      m = message.b.dup
+      pad = RATE - (m.bytesize % RATE)
+      tail = "\x00".b * pad
+      tail.setbyte(0, 0x01)
+      tail.setbyte(pad - 1, tail.getbyte(pad - 1) | 0x80)
+      m << tail
+
+      state = Array.new(25, 0)
+      m.bytes.each_slice(RATE) do |block|
+        (RATE / 8).times { |i| state[i] ^= block[i * 8, 8].pack("C*").unpack1("Q<") }
+        keccak_f(state)
+      end
+      (0..3).map { |i| [state[i]].pack("Q<") }.join.b
+    end
+
+    def hexdigest(message) = digest(message).unpack1("H*")
+
+    def rotl(x, n) = ((x << n) | (x >> (64 - n))) & MASK
+
+    def keccak_f(st)
+      bc = Array.new(5, 0)
+      24.times do |round|
+        5.times { |i| bc[i] = st[i] ^ st[i + 5] ^ st[i + 10] ^ st[i + 15] ^ st[i + 20] }
+        5.times do |i|
+          t = bc[(i + 4) % 5] ^ rotl(bc[(i + 1) % 5], 1)
+          (0...25).step(5) { |j| st[j + i] ^= t }
+        end
+        t = st[1]
+        24.times do |i|
+          j = PILN[i]
+          tmp = st[j]
+          st[j] = rotl(t, ROTC[i])
+          t = tmp
+        end
+        (0...25).step(5) do |j|
+          5.times { |i| bc[i] = st[j + i] }
+          5.times { |i| st[j + i] ^= (~bc[(i + 1) % 5] & MASK) & bc[(i + 2) % 5] }
+        end
+        st[0] ^= RNDC[round]
+        st.map! { |v| v & MASK }
+      end
+    end
+
+    private_class_method :rotl, :keccak_f
+  end
+end

data/lib/opentimestamps/operation.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "digest"
+require "openssl"
+require_relative "keccak256"
+
+module OpenTimestamps
+  # A commitment operation: either a binary op that folds an argument into the
+  # message (append / prepend) or a unary cryptographic digest (sha1 / ripemd160
+  # / sha256). Operations are the edges of a timestamp tree.
+  class Op
+    UNARY  = { 0x02 => :sha1, 0x03 => :ripemd160, 0x08 => :sha256, 0x67 => :keccak256 }.freeze
+    BINARY = { 0xf0 => :append, 0xf1 => :prepend }.freeze
+    TAG    = UNARY.merge(BINARY).invert.freeze
+
+    attr_reader :kind, :arg
+
+    def initialize(kind, arg = nil)
+      raise Error, "unknown op #{kind}" unless TAG.key?(kind)
+      raise Error, "#{kind} takes no argument" if arg && UNARY.value?(kind)
+      raise Error, "#{kind} requires an argument" if arg.nil? && BINARY.value?(kind)
+
+      @kind = kind
+      @arg = arg&.b
+    end
+
+    def binary? = BINARY.value?(@kind)
+
+    # Apply the operation to a message, returning the new bytes.
+    def apply(msg)
+      case @kind
+      when :append   then msg + @arg
+      when :prepend  then @arg + msg
+      when :sha256    then Digest::SHA256.digest(msg)
+      when :sha1      then Digest::SHA1.digest(msg)
+      when :keccak256 then Keccak256.digest(msg)
+      when :ripemd160
+        # OpenSSL 3 hides RIPEMD160 behind the legacy provider; surface a clear error.
+        OpenSSL::Digest.digest("RIPEMD160", msg)
+      end
+    rescue OpenSSL::Digest::DigestError => e
+      raise Error, "ripemd160 unavailable (enable the OpenSSL legacy provider): #{e.message}"
+    end
+
+    def serialize(writer)
+      writer.u8(TAG.fetch(@kind))
+      writer.varbytes(@arg) if binary?
+      writer
+    end
+
+    def self.deserialize(reader, tag)
+      if BINARY.key?(tag)
+        new(BINARY[tag], reader.varbytes)
+      elsif UNARY.key?(tag)
+        new(UNARY[tag])
+      else
+        raise DeserializationError, format("unknown operation tag 0x%02x", tag)
+      end
+    end
+
+    # Value equality so Ops work as Hash keys in a timestamp tree.
+    def ==(other) = other.is_a?(Op) && other.kind == @kind && other.arg == @arg
+    alias eql? ==
+    def hash = [@kind, @arg].hash
+
+    def to_s = binary? ? "#{@kind}(#{@arg.unpack1('H*')})" : @kind.to_s
+  end
+end

data/lib/opentimestamps/serialization.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module OpenTimestamps
+  # Wire primitives shared by every OTS structure: the base-128 varuint,
+  # length-prefixed varbytes, and the detached-file magic header. The reader
+  # treats its input as untrusted and only ever raises DeserializationError.
+  module Serialization
+    MAGIC = "\x00OpenTimestamps\x00\x00Proof\x00\xBF\x89\xE2\xE8\x84\xE8\x92\x94".b
+
+    # Upper bound on any decoded varuint. Real lengths (bounded by a file) and
+    # block heights fit comfortably; the cap stops a crafted length prefix from
+    # producing a bignum that would blow up byteslice.
+    MAX_VARUINT = (1 << 32) - 1
+
+    class Reader
+      def initialize(bytes)
+        @b = bytes.b
+        @i = 0
+      end
+
+      def eof? = @i >= @b.bytesize
+
+      def rest = @b.byteslice(@i..) || "".b
+
+      def u8
+        byte = @b.getbyte(@i) or raise DeserializationError, "unexpected end of input"
+        @i += 1
+        byte
+      end
+
+      def read(n)
+        raise DeserializationError, "want #{n} bytes, #{@b.bytesize - @i} left" if n > @b.bytesize - @i
+
+        s = @b.byteslice(@i, n)
+        @i += n
+        s
+      end
+
+      def varuint
+        result = 0
+        shift = 0
+        loop do
+          byte = u8
+          result |= (byte & 0x7f) << shift
+          raise DeserializationError, "varuint out of range" if result > MAX_VARUINT
+
+          break if (byte & 0x80).zero?
+
+          shift += 7
+        end
+        result
+      end
+
+      def varbytes = read(varuint)
+    end
+
+    class Writer
+      def initialize
+        @string = +"".b
+      end
+
+      attr_reader :string
+
+      def u8(int)
+        @string << int
+        self
+      end
+
+      def write(bytes)
+        @string << bytes.b
+        self
+      end
+
+      def varuint(n)
+        raise Error, "varuint must be non-negative" if n.negative?
+
+        loop do
+          byte = n & 0x7f
+          n >>= 7
+          byte |= 0x80 if n.positive?
+          @string << byte
+          break if n.zero?
+        end
+        self
+      end
+
+      def varbytes(bytes)
+        varuint(bytes.bytesize)
+        write(bytes)
+      end
+    end
+  end
+end

data/lib/opentimestamps/timestamp.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module OpenTimestamps
+  # A node in the timestamp tree: a message, the attestations that commit to it,
+  # and the operations leading to child nodes. Serialization follows the OTS
+  # wire format's 0x00 (attestation) / 0xff (fork) markers.
+  class Timestamp
+    # Caps that keep an untrusted proof from exhausting the process: a depth
+    # limit (real proofs are shallow) and a per-node message-size limit that
+    # bounds append/prepend growth.
+    MAX_DEPTH = 1_000
+    MAX_MSG_BYTES = 1 << 20
+
+    attr_reader :msg, :attestations, :ops # ops: Hash[Op => Timestamp]
+
+    def initialize(msg)
+      @msg = msg.b
+      @attestations = []
+      @ops = {}
+    end
+
+    def self.deserialize(reader, initial_msg, depth = 0)
+      raise DeserializationError, "timestamp nested too deeply" if depth > MAX_DEPTH
+
+      node = new(initial_msg)
+      tag = reader.u8
+      while tag == 0xff # fork: another child follows at this node
+        read_child(reader, node, reader.u8, depth)
+        tag = reader.u8
+      end
+      read_child(reader, node, tag, depth) # the last (or only) child
+      node
+    end
+
+    def self.read_child(reader, node, tag, depth)
+      if tag == 0x00
+        node.attestations << Attestation.deserialize(reader)
+      else
+        op = Op.deserialize(reader, tag)
+        child_msg = op.apply(node.msg)
+        raise DeserializationError, "commitment message too large" if child_msg.bytesize > MAX_MSG_BYTES
+
+        node.ops[op] = deserialize(reader, child_msg, depth + 1)
+      end
+    end
+    private_class_method :read_child
+
+    def serialize(writer)
+      total = @attestations.size + @ops.size
+      raise Error, "timestamp node has no children" if total.zero?
+
+      written = 0
+      @attestations.each do |att|
+        writer.u8(0xff) if (written += 1) < total
+        writer.u8(0x00)
+        att.serialize(writer)
+      end
+      @ops.each do |op, child|
+        writer.u8(0xff) if (written += 1) < total
+        op.serialize(writer)
+        child.serialize(writer)
+      end
+      writer
+    end
+
+    # Yields [commitment_msg, attestation] for every attestation in the tree.
+    def each_attestation(&block)
+      return enum_for(:each_attestation) unless block
+
+      @attestations.each { |att| block.call(@msg, att) }
+      @ops.each_value { |child| child.each_attestation(&block) }
+    end
+
+    # First node whose message equals +target+, or nil.
+    def find(target)
+      return self if @msg == target
+
+      @ops.each_value do |child|
+        found = child.find(target)
+        return found if found
+      end
+      nil
+    end
+
+    # Fold another timestamp rooted at the same message into this one (upgrade).
+    def merge(other)
+      raise Error, "cannot merge: message mismatch" unless other.msg == @msg
+
+      other.attestations.each { |a| @attestations << a unless @attestations.include?(a) }
+      other.ops.each do |op, child|
+        if @ops.key?(op)
+          @ops[op].merge(child)
+        else
+          @ops[op] = child
+        end
+      end
+      self
+    end
+
+    # Checks every Bitcoin attestation against the chain oracle. Returns one
+    # { height:, time:, verified: } entry per Bitcoin attestation.
+    def verify(chain)
+      each_attestation.filter_map do |commitment, att|
+        next unless att.bitcoin?
+
+        root, time = chain.block_merkle_root_and_time(att.height)
+        { height: att.height, time: time, verified: commitment == root }
+      end
+    end
+  end
+end

data/lib/opentimestamps/version.rb

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

data/lib/opentimestamps.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "digest"
+
+require_relative "opentimestamps/version"
+require_relative "opentimestamps/error"
+require_relative "opentimestamps/serialization"
+require_relative "opentimestamps/operation"
+require_relative "opentimestamps/attestation"
+require_relative "opentimestamps/timestamp"
+require_relative "opentimestamps/detached_file"
+require_relative "opentimestamps/calendar"
+require_relative "opentimestamps/chain"
+
+# Client for the OpenTimestamps protocol, in pure Ruby with no runtime
+# dependencies.
+#
+#   ots = OpenTimestamps.stamp("hello world\n")   # DetachedTimestampFile (pending)
+#   File.binwrite("hello.txt.ots", ots.serialize) # persist, or you cannot upgrade
+#   OpenTimestamps.upgrade(ots)                    # hours later: fold in the Bitcoin path
+#   OpenTimestamps.verify(ots)                     # => [Verification(height:, time:, digest:)]
+module OpenTimestamps
+  DEFAULT_CALENDARS = %w[
+    https://alice.btc.calendar.opentimestamps.org
+    https://bob.btc.calendar.opentimestamps.org
+  ].freeze
+
+  # One confirmed Bitcoin attestation: the block that anchors +digest+, and when.
+  Verification = Struct.new(:height, :time, :digest, keyword_init: true)
+
+  module_function
+
+  # Stamp raw data: hash it, then stamp the digest.
+  def stamp(data, calendars: DEFAULT_CALENDARS, hash: :sha256, timeout: 20)
+    stamp_digest(digest_for(data, hash), calendars: calendars, hash: hash, timeout: timeout)
+  end
+
+  # Stamp an already-computed digest. The content itself never leaves the caller
+  # (privacy / "sealed" mode). The digest is submitted to every calendar and the
+  # replies are merged, so a single calendar being down is not fatal.
+  def stamp_digest(digest, calendars: DEFAULT_CALENDARS, hash: :sha256, timeout: 20)
+    DetachedTimestampFile.from_hash(digest, hash: hash) # validate digest length before any network
+
+    merged = nil
+    failures = []
+    Array(calendars).each do |url|
+      timestamp = Calendar.new(url).submit(digest, timeout: timeout)
+      merged ? merged.merge(timestamp) : merged = timestamp
+    rescue NetworkError => e
+      failures << e.message
+    end
+    raise NetworkError, "every calendar failed: #{failures.join('; ')}" if merged.nil?
+
+    DetachedTimestampFile.new(Op.new(hash), merged)
+  end
+
+  # Ask each pending calendar to upgrade to its Bitcoin path, folding the result
+  # in. Returns true if anything changed; persist the file afterwards. A calendar
+  # that is unreachable is skipped, not fatal.
+  def upgrade(detached, timeout: 20)
+    return false if detached.timestamp.each_attestation.any? { |_, att| att.bitcoin? }
+
+    changed = false
+    detached.timestamp.each_attestation.select { |_, att| att.pending? }.each do |commitment, att|
+      upgraded = begin
+        Calendar.new(att.uri).upgrade(commitment, timeout: timeout)
+      rescue NetworkError
+        nil
+      end
+      next unless upgraded
+
+      detached.timestamp.find(commitment)&.merge(upgraded)
+      changed = true
+    end
+    changed
+  end
+
+  # Verify against the chain, failing closed: raises VerificationError unless at
+  # least one Bitcoin attestation matches its block. Returns the confirmed
+  # attestations, each carrying the proven digest to compare with your document.
+  def verify(detached, chain: Chain::Explorer.new)
+    digest = detached.file_digest
+    confirmed = detached.timestamp.verify(chain).select { |result| result[:verified] }
+    raise VerificationError, "not anchored in Bitcoin (still pending, or the proof does not match)" if confirmed.empty?
+
+    confirmed.map { |result| Verification.new(height: result[:height], time: result[:time], digest: digest) }
+  end
+
+  # Boolean form of verify that never raises.
+  def verified?(detached, chain: Chain::Explorer.new)
+    !verify(detached, chain: chain).empty?
+  rescue VerificationError
+    false
+  end
+
+  # Human-readable dump of a proof's structure.
+  def info(detached)
+    lines = ["file digest (#{detached.file_hash_op.kind}): #{detached.file_digest.unpack1('H*')}"]
+    detached.timestamp.each_attestation do |commitment, att|
+      lines << "  #{att} @ #{commitment.unpack1('H*')[0, 32]}..."
+    end
+    lines.join("\n")
+  end
+
+  def digest_for(data, hash)
+    case hash
+    when :sha256 then Digest::SHA256.digest(data)
+    when :sha1   then Digest::SHA1.digest(data)
+    else raise Error, "cannot hash raw data with #{hash.inspect}; pass a precomputed digest to stamp_digest"
+    end
+  end
+  private_class_method :digest_for
+end

metadata

@@ -0,0 +1,94 @@
+--- !ruby/object:Gem::Specification
+name: opentimestamps
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Artem Kolesnikov
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-09-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: |
+  A dependency-free Ruby implementation of the OpenTimestamps protocol: stamp a
+  hash against the Bitcoin blockchain via public calendar servers, upgrade the
+  proof to a block attestation, and verify it - using only the standard library.
+  Proofs are self-verifying and outlive both this gem and any single server.
+email:
+- sirruf@me.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/opentimestamps.rb
+- lib/opentimestamps/attestation.rb
+- lib/opentimestamps/calendar.rb
+- lib/opentimestamps/chain.rb
+- lib/opentimestamps/detached_file.rb
+- lib/opentimestamps/error.rb
+- lib/opentimestamps/keccak256.rb
+- lib/opentimestamps/operation.rb
+- lib/opentimestamps/serialization.rb
+- lib/opentimestamps/timestamp.rb
+- lib/opentimestamps/version.rb
+homepage: https://github.com/sirruf/opentimestamps
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/sirruf/opentimestamps
+  source_code_uri: https://github.com/sirruf/opentimestamps
+  changelog_uri: https://github.com/sirruf/opentimestamps/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/sirruf/opentimestamps/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: 'Pure-Ruby OpenTimestamps client: Bitcoin-anchored timestamps, zero dependencies.'
+test_files: []